@synctek/forgeos 2.0.0 → 2.1.0

package/README.md

@@ -1,109 +1,84 @@
-# @synctek/forgeos-mcp
+# @synctek/forgeos
 
-MCP server that connects Claude Code (and any MCP-compatible AI agent) to the
-[ForgeOS](https://synctek.io/forgeos) governance engine.
+**The governance OS for agentic software teams.**
 
-ForgeOS enforces structured software development through gates, initiatives,
-and quality reviews. This server exposes the ForgeOS engine as 12 typed MCP
-tools so your AI agent can create initiatives, propose changesets, submit
-evidence, run structured reviews, promote gates, and query institutional
-knowledge — all from within a single Claude Code session.
+---
+
+ForgeOS is a **persistent governance, memory, and trust layer** that any AI plugs into. It is not an AI. It is not an orchestrator. Your AI (Claude Code, Codex, Cursor, or any MCP-compatible agent) provides the judgment. ForgeOS provides the enforcement — structured gates that block premature releases, a Shared Mind that accumulates institutional knowledge across every session, and a tamper-evident ledger that proves every decision was made and reviewed correctly.
+
+Session 100 is smarter than session 1 because ForgeOS feeds every past regression, gate failure, anti-pattern, and fix recipe back into your AI's context before it acts.
 
 ---
 
-## Quick Start (stdio — recommended for Claude Code)
+## Why ForgeOS
 
-No install required:
+- **Governance gates** — Risk-scored gate pipelines (intent → design → implementation → verification → hardening → release) block releases that skip required reviews or lack evidence. Gates are not advisory; they are enforced.
+- **Shared Mind** — Institutional memory that persists across sessions. Patterns, anti-patterns, and fix recipes accumulate automatically. Every AI session inherits what past sessions learned.
+- **Ed25519 trust ledger** — Every gate promotion, evidence submission, and review verdict is signed and hash-chained. Decisions are tamper-evident and attributable.
+- **Federation** — Knowledge learned by one team propagates to all teams in your organization. One fix discovered in your payment module becomes a system-wide prevention.
+- **Works with any AI** — ForgeOS exposes 21 MCP tools. If your AI client speaks MCP, it works with ForgeOS. No ForgeOS-specific AI model required.
 
-```bash
-npx -y @synctek/forgeos-mcp
-```
+---
 
-Set your API key and engine URL before running:
+## Install
 
 ```bash
-FORGEOS_API_KEY=your-key FORGEOS_ENGINE_URL=https://api.synctek.io npx -y @synctek/forgeos-mcp
+npm install -g @synctek/forgeos
 ```
 
+Requires Node.js 18+. One command installs three binaries: `forge` (CLI), `forgeos-mcp` (stdio MCP server), `forgeos-mcp-http` (HTTP MCP server).
+
 ---
 
-## Claude Desktop Integration
+## Usage
+
+### Path 1: MCP — for AI agents (Claude Code, Cursor, etc.)
+
+Add ForgeOS to your MCP client configuration. No install required for the MCP server itself — `npx` handles it.
 
-Add to your `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`):
+**Claude Code** (`~/.claude/mcp.json` or project-level `.mcp.json`):
 
 ```json
 {
   "mcpServers": {
     "forgeos": {
       "command": "npx",
-      "args": ["-y", "@synctek/forgeos-mcp"],
+      "args": ["-y", "@synctek/forgeos"],
       "env": {
-        "FORGEOS_API_KEY": "your-api-key-here",
-        "FORGEOS_ENGINE_URL": "https://api.synctek.io"
+        "FORGE_API_KEY": "your-api-key",
+        "FORGE_ENGINE_URL": "https://api.forgeos.synctek.io"
       }
     }
   }
 }
 ```
 
-For Claude Code (`~/.claude/mcp.json` or project-level `.mcp.json`):
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
 {
   "mcpServers": {
     "forgeos": {
       "command": "npx",
-      "args": ["-y", "@synctek/forgeos-mcp"],
+      "args": ["-y", "@synctek/forgeos"],
       "env": {
-        "FORGEOS_API_KEY": "your-api-key-here",
-        "FORGEOS_ENGINE_URL": "https://api.synctek.io"
+        "FORGE_API_KEY": "your-api-key",
+        "FORGE_ENGINE_URL": "https://api.forgeos.synctek.io"
       }
     }
   }
 }
 ```
 
----
-
-## HTTP/SSE Mode
+Once configured, your AI can call `forge_init`, `forge_create_initiative`, `forge_propose_changeset`, and all other ForgeOS tools directly from within a session.
 
-For remote deployments or multi-tenant scenarios, run the HTTP server instead
-of stdio. Each request carries its own Bearer token — no shared state between
-callers.
+**HTTP/SSE mode** (for remote deployments or multi-tenant scenarios):
 
 ```bash
-# Start the HTTP server (default port 8401)
-npx -y @synctek/forgeos-mcp forgeos-mcp-http
-
-# Or after installing globally:
-npm install -g @synctek/forgeos-mcp
+# Start the HTTP MCP server (default port 8401)
 forgeos-mcp-http
 ```
 
-### Endpoints
-
-| Method   | Path      | Description                              |
-|----------|-----------|------------------------------------------|
-| `POST`   | `/mcp`    | StreamableHTTP main channel (JSON-RPC)   |
-| `GET`    | `/mcp`    | SSE fallback (server-to-client events)   |
-| `DELETE` | `/mcp`    | Session cleanup                          |
-| `GET`    | `/health` | Liveness probe — no auth required        |
-
-### Calling the HTTP endpoint
-
-```bash
-# Health check
-curl http://localhost:8401/health
-
-# MCP request with Bearer token
-curl -X POST http://localhost:8401/mcp \
-  -H "Authorization: Bearer your-api-key" \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
-```
-
-### Connecting an MCP client to the HTTP endpoint
-
 ```json
 {
   "mcpServers": {
@@ -118,266 +93,200 @@ curl -X POST http://localhost:8401/mcp \
 }
 ```
 
----
-
-## Configuration
-
-| Environment Variable   | Default                  | Description                                         |
-|------------------------|--------------------------|-----------------------------------------------------|
-| `FORGEOS_API_KEY`      | _(empty)_                | API key sent as `X-ForgeOS-API-Key` header          |
-| `FORGEOS_ENGINE_URL`   | `http://localhost:8400`  | Base URL of the ForgeOS engine                      |
-| `MCP_HTTP_PORT`        | `8401`                   | Port for the HTTP/SSE server                        |
-| `RATE_LIMIT_MAX`       | `60`                     | Max requests per window (HTTP mode)                 |
-| `RATE_LIMIT_WINDOW_MS` | `60000`                  | Rate limit window in milliseconds (HTTP mode)       |
-
----
-
-## Tools Reference
-
-All tools return JSON. Errors surface as `{ "ok": false, "error": "..." }`.
-
-### `forge_init`
-
-Initialize a ForgeOS governance session. Returns project state, active work,
-governance rules, and workflow runbook. Call on every session start.
-
-| Parameter      | Type     | Required | Description                      |
-|----------------|----------|----------|----------------------------------|
-| `project_id`   | `string` | Yes      | Project to initialize            |
-| `developer_id` | `string` | No       | Developer identifier (default: `local`) |
-
----
-
-### `forge_create_initiative`
-
-Create a new initiative to track a piece of work. Returns the initiative with
-a generated ID.
-
-| Parameter     | Type     | Required | Description                             |
-|---------------|----------|----------|-----------------------------------------|
-| `project_id`  | `string` | Yes      | Project ID                              |
-| `title`       | `string` | Yes      | Initiative title                        |
-| `description` | `string` | Yes      | What this initiative accomplishes       |
-| `priority`    | `string` | No       | `low` \| `medium` \| `high` \| `critical` (default: `medium`) |
-
----
-
-### `forge_propose_changeset`
-
-Propose a changeset for an initiative. The engine computes a risk score and
-determines required gates, reviewer roles, and evidence. Returns the changeset
-with a full gate pipeline.
-
-| Parameter          | Type       | Required | Description                        |
-|--------------------|------------|----------|------------------------------------|
-| `project_id`       | `string`   | Yes      | Project ID                         |
-| `initiative_id`    | `string`   | Yes      | Parent initiative                  |
-| `description`      | `string`   | Yes      | What changed and why               |
-| `files_changed`    | `string[]` | Yes      | File paths that changed            |
-| `modules_affected` | `string[]` | Yes      | Module/area names affected         |
-| `branch`           | `string`   | No       | Git branch name                    |
-
----
-
-### `forge_get_profile`
-
-Fetch a reviewer persona profile for subagent injection. When a `project_id`
-is provided, the profile is enriched with Shared Mind patterns from prior
-reviews. Use the returned `system_prompt` as the subagent's instructions.
-
-| Parameter          | Type       | Required | Description                                             |
-|--------------------|------------|----------|---------------------------------------------------------|
-| `role`             | `string`   | Yes      | `architect` \| `qa_test` \| `security` \| `performance` \| `reliability` \| `accessibility` \| `docs_release` |
-| `project_id`       | `string`   | No       | Project for contextualization                           |
-| `team_id`          | `string`   | No       | Team ID for Shared Mind context (default: `default`)    |
-| `modules_affected` | `string[]` | No       | Modules to focus on                                     |
-| `files_changed`    | `string[]` | No       | Files to focus on                                       |
-
----
-
-### `forge_submit_evidence`
+### Path 2: CLI — for humans and CI
 
-Submit evidence (test results, scan outputs, etc.) for a changeset.
-Auto-populates gate evidence requirements.
+```bash
+forge --help
+```
 
-| Parameter      | Type       | Required | Description                                                                                   |
-|----------------|------------|----------|-----------------------------------------------------------------------------------------------|
-| `project_id`   | `string`   | Yes      | Project ID                                                                                    |
-| `changeset_id` | `string`   | Yes      | Changeset ID                                                                                  |
-| `type`         | `string`   | Yes      | `unit_test` \| `coverage` \| `lint` \| `security_scan` \| `benchmark` \| `migration_plan` \| `ux_snapshot` \| `a11y_audit` \| `ai_review` |
-| `summary`      | `string`   | Yes      | Summary of the evidence                                                                       |
-| `file_refs`    | `string[]` | No       | File references                                                                               |
+Common workflows:
 
----
+```bash
+# Start a new governance session for a project
+forge session start --project my-saas-app
 
-### `forge_submit_review`
+# Create an initiative to track a piece of work
+forge initiative create --project my-saas-app --title "Add payment retry logic"
 
-Submit a complete review with findings and verdict. Creates and finalizes the
-review in one call.
+# Propose a changeset; engine computes risk and required gates
+forge changeset propose --project my-saas-app --initiative INIT-001 \
+  --files "src/payments/retry.ts,src/payments/webhook.ts"
 
-| Parameter      | Type       | Required | Description                                   |
-|----------------|------------|----------|-----------------------------------------------|
-| `project_id`   | `string`   | Yes      | Project ID                                    |
-| `changeset_id` | `string`   | Yes      | Changeset ID                                  |
-| `role`         | `string`   | Yes      | Reviewer role (e.g. `security`, `architect`)  |
-| `status`       | `string`   | Yes      | `approved` \| `blocked` \| `pending`          |
-| `notes`        | `string`   | Yes      | Review summary                                |
-| `findings`     | `object[]` | Yes      | Structured findings (see below)               |
+# Check gate status
+forge gate status --project my-saas-app --changeset CS-001
 
-Each finding in `findings`:
+# Submit test evidence to satisfy a gate requirement
+forge evidence submit --project my-saas-app --changeset CS-001 \
+  --type unit_test --summary "All 42 payment retry tests pass"
 
-| Field            | Type     | Required | Description                                    |
-|------------------|----------|----------|------------------------------------------------|
-| `category`       | `string` | Yes      | Finding category                               |
-| `severity`       | `string` | Yes      | `pass` \| `warning` \| `concern` \| `fail`    |
-| `observation`    | `string` | Yes      | What was observed                              |
-| `recommendation` | `string` | No       | Suggested fix                                  |
+# Query Shared Mind for relevant patterns before reviewing
+forge mind query --context "payment retry exponential backoff"
+```
 
 ---
 
-### `forge_check_gates`
+## What ForgeOS provides vs. what your AI provides
 
-Get the gate pipeline status for a changeset. Shows which gates are passed,
-pending, or failed, and what is needed to advance.
+| Capability | ForgeOS | Your AI |
+|---|---|---|
+| Governance gate enforcement | Yes — hard blocks | — |
+| Risk scoring for changesets | Yes — engine-computed | — |
+| Institutional memory (cross-session) | Yes — Shared Mind | No — ephemeral per session |
+| Ed25519 signed audit ledger | Yes | — |
+| Federation across teams | Yes | — |
+| Code judgment and analysis | — | Yes |
+| Review recommendations | — | Yes |
+| Test generation | — | Yes |
+| Natural language reasoning | — | Yes |
 
-| Parameter      | Type     | Required | Description    |
-|----------------|----------|----------|----------------|
-| `project_id`   | `string` | Yes      | Project ID     |
-| `changeset_id` | `string` | Yes      | Changeset ID   |
+Your AI reasons. ForgeOS remembers, enforces, and proves.
 
 ---
 
-### `forge_promote_gate`
+## How it works
 
-Promote a gate to passed status. All requirements (evidence + reviews) must be
-satisfied. Advances the pipeline to the next gate.
+```
+Your codebase (local)
+       │
+       ▼
+Your AI agent  ──(MCP tools)──►  ForgeOS MCP server  ──(REST)──►  ForgeOS engine
+  (Claude, Codex,                  forgeos-mcp (stdio)              (local or hosted)
+   Cursor, etc.)                   forgeos-mcp-http (SSE)
+                                          │
+                                          ▼
+                                   Shared Mind  ◄──  Federation
+                                   Trust ledger
+                                   Gate pipeline
+```
 
-| Parameter      | Type     | Required | Description                                                                                     |
-|----------------|----------|----------|-------------------------------------------------------------------------------------------------|
-| `project_id`   | `string` | Yes      | Project ID                                                                                      |
-| `changeset_id` | `string` | Yes      | Changeset ID                                                                                    |
-| `gate_id`      | `string` | Yes      | `intent` \| `design` \| `implementation` \| `verification` \| `hardening` \| `release`         |
-| `promoted_by`  | `string` | No       | Who is promoting (default: `local_agent`)                                                       |
+The engine runs locally (self-hosted) or on Synctek-hosted infrastructure. Your source code never leaves your machine — the engine receives only metadata: file paths, module names, changeset descriptions, review verdicts. Federation uses a fail-closed privacy scrubber before any data propagates across team boundaries.
 
 ---
 
-### `forge_release_check`
-
-Check if a changeset is ready to release. Returns `can_release` status and any
-remaining blockers.
-
-| Parameter      | Type     | Required | Description    |
-|----------------|----------|----------|----------------|
-| `project_id`   | `string` | Yes      | Project ID     |
-| `changeset_id` | `string` | Yes      | Changeset ID   |
-
----
+## MCP Tools Reference
 
-### `forge_query_mind`
+All tools return JSON. Errors surface as `{ "ok": false, "error": "..." }`.
 
-Search the Shared Mind for institutional knowledge. Returns patterns,
-anti-patterns, and lessons relevant to the given context.
+| Tool | Description |
+|---|---|
+| `forge_init` | Initialize a governance session. Returns project state, active work, governance rules, workflow runbook, and setup scorecard. Call at session start. |
+| `forge_create_project` | Create a new ForgeOS project — the top-level container for initiatives, changesets, and governance workflows. |
+| `forge_quickstart` | Create a sandbox project and run a complete governance cycle in seconds. Ideal for first-time setup and verification. |
+| `forge_discover` | Analyze your repo's tech stack and get a recommended governance configuration, preset, and CI hints. |
+| `forge_get_presets` | List available governance presets: Startup, Enterprise, Regulated, Mobile Release QA. |
+| `forge_configure_project_gates` | Apply a governance preset or custom gate template to a project. Sets which gates are required and what evidence satisfies each. |
+| `forge_scorecard` | Check setup completeness. Shows which onboarding steps are done and what to do next. |
+| `forge_create_initiative` | Create an initiative to track a piece of work. Returns the initiative with a generated ID. |
+| `forge_get_workflow` | Get the current workflow state for an initiative — current step, what is needed next, overall progress. |
+| `forge_workflow_template` | Get copy-paste workflow templates for common scenarios: bugfix, feature, hotfix, release candidate. |
+| `forge_propose_changeset` | Propose a changeset. Engine computes a risk score and determines required gates, reviewer roles, and evidence requirements. |
+| `forge_recommend_gates` | Get a gate recommendation for a changeset based on risk analysis — recommended gates, minimum gates, and rationale. |
+| `forge_get_context` | Get comprehensive context for a changeset: SharedMind patterns, quality warnings, past regressions, and relevant lessons. Call before submitting evidence or reviews. |
+| `forge_check_gates` | Get the gate pipeline status for a changeset — which gates are passed, pending, or failed, and what is needed to advance. |
+| `forge_promote_gate` | Promote a gate to passed status. All evidence and reviewer requirements must be satisfied. Advances the pipeline. |
+| `forge_release_check` | Check if a changeset is ready to release. Returns `can_release` status and any remaining blockers. |
+| `forge_submit_evidence` | Submit evidence (test results, scan outputs, coverage reports, benchmarks) for a changeset. Auto-populates gate requirements. |
+| `forge_submit_review` | Submit a complete review with structured findings and a verdict (`approved` / `blocked` / `pending`). |
+| `forge_get_profile` | Fetch a reviewer persona (architect, security, qa_test, performance, reliability, accessibility, docs_release) enriched with Shared Mind patterns. Returns a `system_prompt` for subagent injection. |
+| `forge_query_mind` | Search the Shared Mind for patterns, anti-patterns, and lessons relevant to a given context or domain. |
+| `forge_observe` | Record a pattern, anti-pattern, fix recipe, architecture decision, or lesson to the Shared Mind. |
+
+### Typical AI agent workflow
 
-| Parameter | Type     | Required | Description                              |
-|-----------|----------|----------|------------------------------------------|
-| `context` | `string` | Yes      | Search context (keywords, module names)  |
-| `team_id` | `string` | No       | Team ID (default: `default`)             |
-| `domain`  | `string` | No       | Specific domain to search                |
+```
+forge_init              → bootstrap session, receive runbook and state
+forge_create_initiative → create initiative, get initiative_id
+forge_propose_changeset → propose work, receive risk score + gate pipeline
+forge_get_context       → pull SharedMind context before reviewing
+forge_get_profile       → fetch reviewer persona enriched with past patterns
+  (run subagent review using the returned system_prompt)
+forge_submit_evidence   → submit test results, scan output, coverage
+forge_submit_review     → record reviewer verdict and findings
+forge_check_gates       → inspect gate pipeline status
+forge_promote_gate      → advance gates as evidence accumulates
+forge_release_check     → confirm all gates cleared before shipping
+forge_observe           → record lessons back to Shared Mind
+```
 
 ---
 
-### `forge_observe`
-
-Record an observation to the Shared Mind. Use when you discover patterns,
-anti-patterns, or lessons during development.
-
-| Parameter          | Type       | Required | Description                                                                     |
-|--------------------|------------|----------|---------------------------------------------------------------------------------|
-| `domain`           | `string`   | Yes      | Knowledge domain (e.g. module name, technology)                                 |
-| `observation_type` | `string`   | Yes      | `pattern` \| `anti-pattern` \| `fix-recipe` \| `architecture-decision` \| `lesson` |
-| `content`          | `string`   | Yes      | What was observed                                                               |
-| `team_id`          | `string`   | No       | Team ID (default: `default`)                                                    |
-| `confidence`       | `number`   | No       | Confidence 0.0–1.0 (default: `0.8`)                                             |
-| `tags`             | `string[]` | No       | Tags for categorization                                                         |
+## CLI Commands Reference
+
+The `forge` binary exposes 14 command groups:
+
+| Group | Description |
+|---|---|
+| `forge project` | Create, list, and configure projects |
+| `forge initiative` | Create and manage initiatives |
+| `forge changeset` | Propose changesets, view risk analysis |
+| `forge gate` | Check status, promote gates, view pipeline |
+| `forge evidence` | Submit and list evidence for changesets |
+| `forge review` | Submit reviews, list reviewer verdicts |
+| `forge session` | Start and manage governance sessions |
+| `forge mind` | Query and write to the Shared Mind |
+| `forge trust` | Inspect trust scores, verify ledger signatures |
+| `forge federation` | Manage cross-team knowledge federation |
+| `forge analyze` | Analyze changesets, modules, and risk |
+| `forge score` | View quality scores and trust metrics |
+| `forge build` | Build and deployment governance workflows |
+| `forge outcome` | Track and report on initiative outcomes |
+
+Run `forge <group> --help` for subcommands.
 
 ---
 
-### `forge_get_workflow`
-
-Get the current workflow state for an initiative. Shows which step the
-developer is on, what is needed next, and overall progress.
-
-| Parameter       | Type     | Required | Description    |
-|-----------------|----------|----------|----------------|
-| `initiative_id` | `string` | Yes      | Initiative ID  |
+## Configuration
 
----
+| Variable | Default | Description |
+|---|---|---|
+| `FORGE_API_KEY` | _(empty)_ | API key for the ForgeOS engine |
+| `FORGE_ENGINE_URL` | `http://localhost:8000` | Engine base URL |
+| `MCP_HTTP_PORT` | `8401` | Port for the HTTP/SSE MCP server |
+| `RATE_LIMIT_MAX` | `60` | Max requests per window (HTTP mode) |
+| `RATE_LIMIT_WINDOW_MS` | `60000` | Rate limit window in ms (HTTP mode) |
 
-## Typical Workflow
+Config file alternative (`~/.forgeos/config.json`):
 
-```
-forge_init             → bootstrap session, get runbook
-forge_create_initiative → create initiative, get initiative_id
-forge_propose_changeset → propose work, engine computes risk + gates
-forge_get_profile       → fetch reviewer persona (optional: enrich with Shared Mind)
-  (run subagent review using returned system_prompt)
-forge_submit_evidence   → upload test results, scan output, etc.
-forge_submit_review     → record reviewer verdict + findings
-forge_check_gates       → inspect gate pipeline status
-forge_promote_gate      → advance gates as evidence accumulates
-forge_release_check     → confirm all gates cleared before shipping
-forge_observe           → record lessons learned back to Shared Mind
+```json
+{
+  "engine_url": "https://api.forgeos.synctek.io",
+  "api_key": "your-api-key"
+}
 ```
 
 ---
 
-## Security
+## Trust and Security
 
-- **Per-request auth isolation** — the HTTP server creates a new `ForgeOSClient`
-  per request, threaded from the `Authorization: Bearer <key>` header.
-  `process.env` is never mutated and there is no shared singleton across requests.
-- **Rate limiting** — token-bucket per API key (or IP fallback).
-  Default: 60 requests per 60-second window. Configurable via `RATE_LIMIT_MAX`
-  and `RATE_LIMIT_WINDOW_MS`.
-- **No credential leakage** — stdio mode reads `FORGEOS_API_KEY` from env once
-  at startup (single-tenant). HTTP mode never touches env for key resolution.
-- **CORS** — all origins allowed by default (clients are local AI agents).
-  Restrict in production by configuring a reverse proxy.
+- **Ed25519 signed ledger** — Every gate promotion, evidence submission, and review is signed with Ed25519 and hash-chained. The audit trail is tamper-evident and independently verifiable.
+- **Source code never transmitted** — The engine receives metadata only: file paths, module names, changeset descriptions, verdicts. Your source code stays on your machine.
+- **Fail-closed privacy scrubber** — Federation runs all observations through a privacy scrubber before propagating cross-team. If the scrubber cannot confirm safety, the observation is blocked, not passed.
+- **Per-request auth isolation (HTTP mode)** — A new client instance is created per request from the `Authorization: Bearer` header. `process.env` is never mutated; no shared singleton across requests.
+- **Rate limiting** — Token-bucket per API key (or IP fallback). Default: 60 requests per 60-second window, configurable.
+- **Local-first** — The engine can run entirely on your own infrastructure. No data leaves your environment unless you opt into hosted infrastructure.
 
 ---
 
-## Development
+## Pricing
 
-```bash
-# Clone and install
-git clone https://github.com/synctek/forgeos-mcp
-cd forgeos-mcp
-npm install
-
-# Run stdio server in dev mode (tsx, no build required)
-npm run dev
-
-# Run HTTP server in dev mode
-npm run dev:http
+[https://forgeos.synctek.io/pricing](https://forgeos.synctek.io/pricing)
 
-# Build
-npm run build
+| Plan | Price | Best for |
+|---|---|---|
+| Pro | $49/mo | Individual developers and small teams |
+| Team | $149/mo | Engineering teams with federation needs |
+| Enterprise | Custom | Regulated industries, on-prem deployments |
 
-# Run built stdio server
-npm start
-
-# Run built HTTP server
-npm run start:http
-```
+14-day free trial. No credit card required to start.
 
 ---
 
 ## Links
 
-- Product: [synctek.io/forgeos](https://synctek.io/forgeos)
+- Website: [forgeos.synctek.io](https://forgeos.synctek.io)
 - Docs: [docs.synctek.io/forgeos](https://docs.synctek.io/forgeos)
 - Issues: [github.com/synctek/forgeos-mcp/issues](https://github.com/synctek/forgeos-mcp/issues)
-- npm: [@synctek/forgeos-mcp](https://www.npmjs.com/package/@synctek/forgeos-mcp)
+- npm: [@synctek/forgeos](https://www.npmjs.com/package/@synctek/forgeos)
 
 ---
 

package/dist/cli/commands/evidence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAUvD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,aAAa,GACpB,IAAI,CA2GN"}
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAiCvD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,aAAa,GACpB,IAAI,CA6GN"}

package/dist/cli/commands/evidence.js

@@ -7,6 +7,22 @@
  *   forge evidence list   --project <pid> --changeset <cid> --gate <gid>
  */
 import { formatTable, formatJSON, formatSuccess, formatError, } from "../output.js";
+// ---------------------------------------------------------------------------
+// SharedMind auto-observation helper (fire-and-forget)
+// Records what evidence types teams produce so SharedMind accumulates
+// knowledge about team quality patterns and evidence coverage gaps.
+// ---------------------------------------------------------------------------
+function observeEvidenceSubmit(client, changesetId, gateId, evidenceType, summary) {
+    client
+        .post(`/api/shared-mind/default/observe`, {
+        domain: evidenceType || "evidence",
+        content: `Evidence (${evidenceType}) submitted for gate ${gateId} on changeset ${changesetId}: ${summary}`,
+        type: "pattern",
+        confidence: 0.5,
+        source_agent: "cli_forge",
+    })
+        .catch(() => { }); // fire-and-forget — never surface errors to user
+}
 export function registerEvidenceCommands(parent, client) {
     const evidence = parent
         .command("evidence")
@@ -36,6 +52,7 @@ export function registerEvidenceCommands(parent, client) {
             const data = (await client.post(`/api/projects/${opts.project}/changesets/${opts.changeset}/gates/${opts.gate}/evidence`, body));
             if (opts.json) {
                 console.log(formatJSON(data));
+                observeEvidenceSubmit(client, opts.changeset, opts.gate, opts.type, opts.content);
                 return;
             }
             const evidenceId = data.id ?? "—";
@@ -46,6 +63,7 @@ export function registerEvidenceCommands(parent, client) {
                 ["Summary", data.summary ?? opts.content],
                 ["Submitted By", data.submitted_by ?? "—"],
             ]));
+            observeEvidenceSubmit(client, opts.changeset, opts.gate, opts.type, opts.content);
         }
         catch (err) {
             console.error(formatError(err));

package/dist/cli/commands/evidence.js.map

@@ -1 +1 @@
-{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../../src/cli/commands/evidence.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../../src/cli/commands/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EACL,WAAW,EACX,UAAU,EACV,aAAa,EACb,WAAW,GACZ,MAAM,cAAc,CAAC;AAEtB,8EAA8E;AAC9E,uDAAuD;AACvD,sEAAsE;AACtE,oEAAoE;AACpE,8EAA8E;AAC9E,SAAS,qBAAqB,CAC5B,MAAqB,EACrB,WAAmB,EACnB,MAAc,EACd,YAAoB,EACpB,OAAe;IAEf,MAAM;SACH,IAAI,CAAC,kCAAkC,EAAE;QACxC,MAAM,EAAE,YAAY,IAAI,UAAU;QAClC,OAAO,EAAE,aAAa,YAAY,wBAAwB,MAAM,iBAAiB,WAAW,KAAK,OAAO,EAAE;QAC1G,IAAI,EAAE,SAAS;QACf,UAAU,EAAE,GAAG;QACf,YAAY,EAAE,WAAW;KAC1B,CAAC;SACD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,iDAAiD;AACvE,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,MAAe,EACf,MAAqB;IAErB,MAAM,QAAQ,GAAG,MAAM;SACpB,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAEvC,4EAA4E;IAC5E,kBAAkB;IAClB,4EAA4E;IAE5E,QAAQ;SACL,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,4BAA4B,CAAC;SACzC,cAAc,CAAC,qBAAqB,EAAE,YAAY,CAAC;SACnD,cAAc,CAAC,mBAAmB,EAAE,cAAc,CAAC;SACnD,cAAc,CAAC,cAAc,EAAE,SAAS,CAAC;SACzC,cAAc,CAAC,eAAe,EAAE,qDAAqD,CAAC;SACtF,cAAc,CAAC,qBAAqB,EAAE,4BAA4B,CAAC;SACnE,MAAM,CAAC,oBAAoB,EAAE,iCAAiC,EAAE,EAAE,CAAC;SACnE,MAAM,CAAC,QAAQ,EAAE,iBAAiB,CAAC;SACnC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACrB,IAAI,CAAC;YACH,MAAM,IAAI,GAA4B;gBACpC,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,SAAS,EAAE,IAAI,CAAC,QAAQ;oBACtB,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;oBACvE,CAAC,CAAC,EAAE;aACP,CAAC;YAEF,MAAM,IAAI,GAAG,CAAC,MAAM,MAAM,CAAC,IAAI,CAC7B,iBAAiB,IAAI,CAAC,OAAO,eAAe,IAAI,CAAC,SAAS,UAAU,IAAI,CAAC,IAAI,WAAW,EACxF,IAAI,CACL,CAAa,CAAC;YAEf,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC9B,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;gBAClF,OAAO;YACT,CAAC;YAED,MAAM,UAAU,GAAG,IAAI,CAAC,EAAE,IAAI,GAAG,CAAC;YAClC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,uBAAuB,UAAU,EAAE,CAAC,CAAC,CAAC;YAChE,OAAO,CAAC,GAAG,CACT,WAAW,CACT,CAAC,OAAO,EAAE,OAAO,CAAC,EAClB;gBACE,CAAC,IAAI,EAAE,UAAU,CAAC;gBAClB,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC;gBAChC,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC;gBACzC,CAAC,cAAc,EAAE,IAAI,CAAC,YAAY,IAAI,GAAG,CAAC;aAC3C,CACF,CACF,CAAC;YACF,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACpF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAA4B,CAAC,CAAC,CAAC;YACzD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,4EAA4E;IAC5E,gBAAgB;IAChB,4EAA4E;IAE5E,QAAQ;SACL,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,0BAA0B,CAAC;SACvC,cAAc,CAAC,qBAAqB,EAAE,YAAY,CAAC;SACnD,cAAc,CAAC,mBAAmB,EAAE,cAAc,CAAC;SACnD,cAAc,CAAC,cAAc,EAAE,SAAS,CAAC;SACzC,MAAM,CAAC,QAAQ,EAAE,iBAAiB,CAAC;SACnC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACrB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAC3B,iBAAiB,IAAI,CAAC,OAAO,eAAe,IAAI,CAAC,SAAS,UAAU,IAAI,CAAC,IAAI,WAAW,CACzF,CAAC;YAEF,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC9B,OAAO;YACT,CAAC;YAED,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;gBAC/B,CAAC,CAAE,IAAmB;gBACtB,CAAC,CAAC,CAAE,IAAkC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;YAEzD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,OAAO,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;gBACpD,OAAO;YACT,CAAC;YAED,OAAO,CAAC,GAAG,CACT,WAAW,CACT,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,CAAC,EACzC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;gBACf,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,EAAE;oBACnB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK;oBACpC,CAAC,CAAC,CAAC,CAAC,OAAO;gBACb,CAAC,CAAC,YAAY;aACf,CAAC,CACH,CACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAA4B,CAAC,CAAC,CAAC;YACzD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/commands/federation.d.ts

@@ -2,10 +2,15 @@
  * `forge federation` — Federation operations.
  *
  * Subcommands:
- *   forge federation status --project <pid>
- *   forge federation enable --project <pid>
- *   forge federation push   --project <pid>
- *   forge federation ingest --project <pid>
+ *   forge federation status  — GET /v1/federation/status → show enabled/disabled,
+ *                               consent flags, last push/pull timestamps
+ *   forge federation enable  — POST /v1/federation/enable with per-flag consent
+ *                               (share_governance_patterns, share_usage_metrics,
+ *                               receive_ecosystem_insights)
+ *   forge federation disable — POST /v1/federation/disable → opt out
+ *   forge federation push    — POST /v1/federation/push → manual push to hub
+ *   forge federation ingest  — POST /v1/federation/ingest → pull insights from hub
+ *                               and write to local SharedMind
  */
 import { Command } from "commander";
 import { ForgeOSClient } from "../../shared/client.js";

package/dist/cli/commands/federation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"federation.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/federation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAavD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,aAAa,GACpB,IAAI,CAsIN"}
+{"version":3,"file":"federation.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/federation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAcvD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,aAAa,GACpB,IAAI,CAqMN"}