workspai 0.58.0 → 0.59.1

package/docs/agent-entry.md

@@ -0,0 +1,194 @@
+# Canonical-First Agent Entry
+
+Workspai gives coding agents one portable way to enter an adopted project
+without treating a broad repository scan as the source of architectural truth.
+
+The protocol is:
+
+```text
+Host discovery
+  → portable project entry
+  → canonical identity and evidence
+  → freshness and integrity checks
+  → active Goal handoff
+  → bounded Graph retrieval
+  → targeted live source inspection
+```
+
+This is deliberately **host-first, not model-first**. A model does not decide
+which repository instruction file is loaded. Codex, Claude Code, Gemini CLI,
+Qwen Code, Kimi Code, GitHub Copilot, Cursor, Windsurf, Amazon Q, Grok, and
+other agent harnesses each own their discovery behavior. Workspai projects one
+canonical protocol through the entry surface each host supports.
+
+## Start from an adopted project
+
+Adopt or import the project once:
+
+```bash
+npx workspai adopt .
+```
+
+When the eventual agent host is not known, run the canonical chain with
+`--for-agent generic`:
+
+```bash
+npx workspai workspace intelligence run --for-agent generic --strict --json
+```
+
+`generic` creates one consumer-neutral context pack and projects lightweight
+entry surfaces for **all supported agent hosts**. It does not build a separate
+Model or Graph for every provider. A later host can therefore discover the
+same canonical evidence without repeating the expensive intelligence run.
+Choosing a named agent may tune the shared context consumer, but the canonical
+chain still preserves portable entry coverage for every supported host.
+
+Workspai writes a portable entry contract at
+`.workspai/agent-entry.v1.json`, a bounded project lens at
+`.workspai/reports/project-context-agent.json`, and host adapters when project
+grounding is managed.
+
+At the start of an agent session, issue a receipt from the project directory:
+
+```bash
+npx workspai agent bootstrap --for-agent codex --strict --json
+```
+
+Use `generic` when the host has no dedicated identifier. Use the legacy
+`orca` input only for compatibility; Workspai resolves it to `grok`.
+
+Audit every supported host in CI or before publishing project grounding:
+
+```bash
+npx workspai project agent-entry verify --for-agent all --strict --json
+```
+
+## What the receipt proves
+
+The `workspai.agent-bootstrap-receipt.v1` payload checks:
+
+- canonical project-to-workspace membership;
+- entry manifest and project-context integrity hashes;
+- host discovery files without overwriting authored repository state;
+- presence and schema validity of the report index, agent context, Workspace
+  Model, and Knowledge Graph;
+- persisted Model/Graph compatibility;
+- live project input compatibility, unless explicitly skipped;
+- active Goal Pack and agent-handoff bindings;
+- portable output with no machine-local absolute paths.
+
+The receipt does not claim that a model followed the instructions. It proves
+that the host has a valid route to current Workspai evidence and tells the
+consumer what it may claim next. The portable manifest keeps `generic` as its
+provider-neutral bootstrap command; each runtime receipt replaces that step in
+`requiredReadOrder` with the resolved host (or `all` for a complete host audit),
+so a consumer is never routed back through the wrong adapter.
+
+The generated workspace name is a logical identity, never a filesystem path.
+Project-local artifacts use `.workspai/...`; canonical workspace artifacts use
+the `workspace:` URI prefix. When an agent requires direct file access, it
+resolves the exact local workspace root at runtime from the adopted project:
+
+```bash
+workspai project workspace status --json
+```
+
+That resolver intentionally returns absolute paths to the local process. Its
+contract classifies them as machine-local, non-portable, forbidden to persist,
+and forbidden to disclose. Entry manifests, project lenses, bootstrap receipts,
+answers, shared logs, commits, prompts, and telemetry must not copy those paths.
+
+| Status     | Meaning                                                               | Consumer rule                                                               |
+| ---------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `ready`    | Host entry, contracts, integrity, and live evidence passed            | Continue with bounded Graph retrieval and targeted source reads             |
+| `degraded` | Evidence is usable with an explicit limitation                        | Disclose the limitation; do not claim complete architecture or verification |
+| `blocked`  | Required discovery, binding, contract, integrity, or freshness failed | Refresh or repair evidence before architectural or verification claims      |
+
+An active Goal is reported independently as `ready`, `stale`, or `invalid`.
+A stale Goal remains `present: true`; the receipt includes a complete refresh
+command in `nextActions`. Absence is represented as `present: false` with
+`status: none`, never as a validation failure.
+
+`--strict` returns exit code `2` for both `degraded` and `blocked`. Without
+`--strict`, a blocked receipt still returns exit code `2`; degraded evidence is
+returned for an explicitly limited read-only workflow.
+
+`--no-live-inputs` is an intentional degraded mode. It checks persisted
+compatibility but cannot prove that the source tree still matches the last
+intelligence run.
+
+## Authority boundaries
+
+Workspai does not replace source code with generated summaries:
+
+- live source owns exact implementation behavior;
+- the canonical Workspace Model owns workspace identity and structural truth;
+- the Knowledge Graph is a model-bound, proof-backed retrieval projection;
+- CLI evidence owns readiness, verification, repair, and Goal lifecycle claims;
+- the project entry contract owns the order in which an agent reaches those
+  sources.
+
+This means an agent begins with canonical evidence, then verifies and deepens
+it through narrow source inspection. It must not silently replace missing or
+stale workspace evidence with an unbounded repository scan.
+
+## Host projection
+
+| Host                                                     | Project discovery surface                                |
+| -------------------------------------------------------- | -------------------------------------------------------- |
+| Generic and unsupported model-only clients               | `.workspai/PROJECT-GROUNDING.md` plus explicit bootstrap |
+| Codex, Kimi Code, GitHub Copilot, Cursor, Windsurf, Grok | `AGENTS.md`                                              |
+| Claude Code                                              | `CLAUDE.md` adapter                                      |
+| Gemini CLI                                               | `GEMINI.md` adapter                                      |
+| Qwen Code                                                | `QWEN.md` adapter                                        |
+| Amazon Q                                                 | `.amazonq/rules/workspai-agent-entry.md`                 |
+
+The adapters contain routing instructions, not duplicated model or graph
+state. The manifest records whether each surface is native, adapted, or a
+portable fallback and whether Workspai could manage it safely.
+
+This matrix was last checked against official host documentation on
+2026-08-16: [Codex `AGENTS.md`](https://learn.chatgpt.com/docs/agent-configuration/agents-md),
+[Claude Code memory](https://code.claude.com/docs/en/memory),
+[Gemini CLI context files](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md),
+[Qwen Code settings](https://github.com/QwenLM/qwen-code/blob/main/docs/users/configuration/settings.md),
+[Kimi Code `AGENTS.md`](https://www.kimi.com/code/docs/en/kimi-code-cli/customization/agents),
+[GitHub Copilot repository instructions](https://docs.github.com/en/copilot/concepts/prompting/response-customization),
+[Cursor rules](https://docs.cursor.com/context/rules-for-ai),
+[Windsurf `AGENTS.md`](https://docs.windsurf.com/windsurf/cascade/agents-md),
+[Amazon Q project rules](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/context-project-rules.html),
+and [Grok skills and instructions](https://docs.x.ai/build/features/skills-plugins-marketplaces).
+DeepSeek, Mistral, hosted model APIs, and other model-only consumers do not
+define a provider-wide repository entry surface independently of the agent
+host. They use the generic portable bootstrap unless their host maps to one of
+the verified surfaces above. Workspai does not invent a model-specific file
+name from undocumented behavior.
+
+If an authored instruction file or symbolic link prevents safe management,
+Workspai preserves repository ownership and reports degraded or blocked host
+coverage. It does not replace the file to make a check pass.
+
+## Consumer integration
+
+IDEs and agent runtimes should:
+
+1. discover the host-native instruction file;
+2. run `workspai agent bootstrap --for-agent <host> --json`;
+3. validate the receipt schema from the installed CLI contract catalog;
+4. stop broad discovery when the receipt is blocked;
+5. read an applicable active Goal handoff before planning changes;
+6. use the bounded Graph query returned by `nextActions`;
+7. open only returned proofs and target source files;
+8. make mutation and verification claims only through the governed CLI flow.
+
+Do not infer support from the package version alone. Discover
+`projectAgentEntry` and `agentBootstrapReceipt` through
+`contracts/published-contract-catalog.v1.json`.
+
+## Package boundary
+
+The CLI currently owns adoption, synchronization, receipt orchestration, and
+exit semantics. The entry manifest and receipt are versioned, portable
+contracts rather than CLI-internal objects. Future independent Model, Graph,
+Goal, or agent packages can therefore implement their own providers behind the
+same contract without changing the project-facing protocol.

package/docs/ci-workflows.md

@@ -22,6 +22,16 @@ The release workflow requires the cost-bounded
 normal push that touches the contracted generator surface produces this gate;
 maintainers do not need to run the full cross-platform matrix before publishing.
 
+Consumer mirror synchronization does not add another required CLI workflow.
+Local pre-commit synchronizes mirrors when contract sources are staged;
+pre-push requires canonical CLI outputs to be committed but does not require a
+consumer release. The extension's own CI remains responsible for hard parity
+against the CLI version selected for that extension release. Consumer-owned
+version floors remain separate from CLI-owned schema inventories, preventing
+parity checks from coupling product versions. Breaking contract removal or
+incompatible schema changes remain CLI release blockers through the canonical
+compatibility and schema-version gates.
+
 Pushes and pull requests run every contracted generator on the primary Linux
 lane. The weekly schedule and manual dispatch can run the complete Linux,
 macOS, and Windows matrix as a non-blocking compatibility and upstream-drift
@@ -30,6 +40,13 @@ caching generated projects; every smoke run still exercises the current
 upstream generator, generated artifacts, build surface, registry, and Doctor
 evidence.
 
+The Windows coverage lane intentionally uses bounded Vitest worker concurrency
+and platform-aware transaction timeouts. Filesystem-heavy workspace tests must
+finish their transaction before teardown; cleanup retries transient Windows
+`EBUSY` and `ENOTEMPTY` states instead of converting one slow operation into a
+cascade of unrelated missing-file failures. These budgets remain finite and do
+not retry failed assertions or product operations.
+
 ## Release announcements
 
 `packages/cli/releases/release-products.v1.json` maps a release product to its
@@ -46,7 +63,7 @@ Validate or preview the current CLI announcement locally:
 npm --workspace workspai run check:release-announcement
 npm --workspace workspai run release:announcement -- \
   --product workspai-cli \
-  --tag v0.58.0 \
+  --tag v0.59.1 \
   --markdown-output /tmp/workspai-discord-announcement.md
 ```
 

package/docs/commands-reference.md

@@ -8,6 +8,20 @@ For behavior and workflows, see
 [workspace-operations.md](./workspace-operations.md) and
 [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md).
 
+Start with the outcome-oriented root help when you do not yet know a command:
+
+```bash
+npx workspai --help
+npx workspai <command> --help
+npx workspai commands --json
+```
+
+Root help presents the canonical `Understand → Impact → Act → Verify` path,
+common human workflows, interactive official-kit discovery through `create
+project`, and a complete ownership-grouped command map. Scoped help carries
+exact flags and examples. `commands --json` remains the machine-complete
+inventory used to prevent the human map from drifting.
+
 ## Workspace lifecycle
 
 ```bash
@@ -21,6 +35,7 @@ npx workspai readiness [--workspace <path>] [--json] [--strict] [--skip-verify]
 npx workspai autopilot release [--mode <audit|safe-fix|enforce>] [--json] [--output <file>] [--since <ref>] [--parallel] [--max-workers <n>]
 npx workspai goal <intent> [--workspace <path>] [--scope <workspace|project:name>] [--for-agent <generic|claude|codex>] [--max-attempts <1-25>] [--refresh] [--dry-run] [--json]
 npx workspai goal <--status [goal-id]|--list|--activate <goal-id>|--cancel <goal-id>|--prepare <goal-id>|--verify <goal-id>> [--workspace <path>] [--no-run] [--json]
+npx workspai agent bootstrap [--project <path>] [--for-agent <host>] [--no-live-inputs] [--strict] [--json]
 ```
 
 Recommended CI:
@@ -59,6 +74,7 @@ npx workspai doctor
 npx workspai doctor workspace [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
 npx workspai doctor project [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
 npx workspai project coverage [--project <path>] [--target <0-100>] [--run] [--strict] [--json]
+npx workspai project agent-entry [verify] [--project <path>] [--for-agent <host|all>] [--no-live-inputs] [--strict] [--json]
 npx workspai workspace list
 npx workspai workspace foundation ensure [--force] [--json]
 npx workspai workspace share [--output <file>] [--include-paths] [--no-doctor]
@@ -71,8 +87,8 @@ npx workspai workspace goal plan <release-readiness|dependency-security|test-cov
 npx workspai workspace goal status <goal-id> [--json]
 npx workspai workspace goal verify <goal-id> [--no-run] [--reuse-intelligence] [--json]
 npx workspai workspace model [--workspace <path>] [--json] [--write] [--strict] [--cache] [--incremental] [--include-paths] [--include-evidence] [--scan-depth <count>]
-npx workspai workspace context --for-agent [generic|codex|claude|cursor|orca] [--workspace <path>] [--scope project:<name>] [--json] [--write] [--agent-sync|--no-agent-sync] [--target <targets>] [--preset minimal|enterprise] [--project-grounding managed|local|off] [--include-evidence] [--scan-depth <count>] [--strict]
-npx workspai workspace agent-sync [--workspace <path>] [--write] [--refresh-context] [--strict] [--json] [--preset minimal|enterprise] [--target all|vscode|agents,copilot,cursor,claude,codex,orca] [--project-grounding managed|local|off] [--experimental-hooks] [--hydrate-prompts]
+npx workspai workspace context --for-agent [generic|codex|claude|gemini|qwen|kimi|grok|copilot|cursor|windsurf|amazon-q] [--workspace <path>] [--scope project:<name>] [--json] [--write] [--agent-sync|--no-agent-sync] [--target <targets>] [--preset minimal|enterprise] [--project-grounding managed|local|off] [--include-evidence] [--scan-depth <count>] [--strict]
+npx workspai workspace agent-sync [--workspace <path>] [--write] [--refresh-context] [--strict] [--json] [--preset minimal|enterprise] [--target all|vscode|agents,copilot,cursor,claude,codex,gemini,qwen,kimi,grok,windsurf,amazon-q] [--project-grounding managed|local|off] [--experimental-hooks] [--hydrate-prompts]
 npx workspai workspace remediation-plan [--json] [--write] [--ci] [--include-paths]
 npx workspai workspace repair <capabilities|plan|propose|approve|decide|execute|resume|status|list|rollback|cancel> [--workspace <path>] [--card <id>] [--action-id <id>] [--project <name>] [--proposal <file>] [--transaction <id>] [--approved-by <actor>] [--decision <choice>] [--max-risk safe|guarded|invasive] [--allow-breaking] [--allow-force] [--no-auto-rollback] [--json]
 npx workspai workspace snapshot [--workspace <path>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
@@ -165,6 +181,14 @@ claim verification. Lifecycle operations are mutually exclusive, cannot be
 combined with an intent or planning-only flags, and `--no-run` is valid only
 with `--verify`. See [Goal Packs](./goal-packs.md).
 
+`agent bootstrap` is the project-local canonical-first preflight. It validates
+the host discovery route, project/workspace binding, public artifact schemas,
+integrity hashes, Model/Graph freshness, live source inputs, and active Goal
+handoff before broad repository discovery. `project agent-entry verify` uses
+the same receipt and can audit every supported host with `--for-agent all`.
+Blocked receipts exit `2`; strict mode also maps degraded evidence to exit `2`.
+See [Canonical-first agent entry](./agent-entry.md).
+
 `workspace feedback record` is a non-interactive machine interface. It requires
 exactly one JSON object on stdin and `--json`; an empty stdin or interactive TTY
 is rejected. Required fields are `actionId`, `summary`, and `outcome`. The

package/docs/contracts/ARTIFACT_CATALOG.md

@@ -28,6 +28,7 @@ root:
 | Artifact                                       | Writer                                                                            | Schema / format             | Portability and reader purpose                                                        |
 | ---------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------- |
 | `.workspai/workspace-link.local.json`          | `adopt`, `import`, project creation, `workspace sync`, `project workspace relink` | `project-workspace-link.v1` | Machine-local absolute binding; always gitignored and never an agent evidence payload |
+| `.workspai/agent-entry.v1.json`                | Project lens reconciliation and `workspace agent-sync --write`                    | `workspai.agent-entry.v1`   | Portable host-discovery, canonical read-order, authority, and integrity contract      |
 | `.workspai/reports/project-context-agent.json` | Project lens reconciliation and `workspace agent-sync --write`                    | `project-context-agent.v1`  | Portable bounded model/graph/proof projection for project-local agents                |
 | `.workspai/PROJECT-GROUNDING.md`               | Project lens reconciliation                                                       | Markdown                    | Portable human/agent entry guide with path-free workspace references                  |
 | `AGENTS.md` managed section                    | Project lens reconciliation in `managed` mode                                     | Managed Markdown block      | Preserves user content and routes compatible agents to project/workspace evidence     |
@@ -42,6 +43,11 @@ machine-local link publishable. The context is bounded but not count-only: it
 includes topology, API/deployment/test surfaces, blockers, portable proofs,
 and model/graph freshness for the selected project.
 
+`agent bootstrap --json` and `project agent-entry verify --json` emit a
+non-persisted `workspai.agent-bootstrap-receipt.v1` payload. The receipt proves
+the selected host route, contract validity, integrity, persisted and live
+freshness, and active Goal bindings without exposing the machine-local link.
+
 ## Naming conventions
 
 | Pattern           | Meaning                                | Examples                                                     |
@@ -62,9 +68,9 @@ and model/graph freshness for the selected project.
 | `workspace remediation-plan --write` | `.workspai/reports/artifact-remediation-plan-last-run.json` | `artifact-remediation-plan-v1`              | `contracts/artifact-remediation-plan.v1.json`                           |
 | `workspace repair *`                 | `.workspai/reports/workspace-repair-last-run.json`          | `workspai.workspace-repair-transaction.v1`  | `contracts/workspace-intelligence/workspace-repair-transaction.v1.json` |
 | `workspace repair capabilities`      | CLI capability output                                       | `workspai.workspace-repair-capabilities.v1` | `contracts/workspace-repair-capabilities.v1.json`                       |
-| `goal <intent>`                      | `.workspai/reports/goal-pack-last-run.json`                  | `workspai.goal-pack.v1`                     | `contracts/workspace-intelligence/goal-pack.v1.json`                    |
-| `goal <intent>` / lifecycle options  | `.workspai/goals/index.json`                                 | `workspai.goal-index.v1`                    | `contracts/workspace-intelligence/goal-index.v1.json`                   |
-| `goal --status/--list/... --json`    | stdout                                                       | `workspai.goal-lifecycle-result.v1`         | `contracts/workspace-intelligence/goal-lifecycle-result.v1.json`        |
+| `goal <intent>`                      | `.workspai/reports/goal-pack-last-run.json`                 | `workspai.goal-pack.v1`                     | `contracts/workspace-intelligence/goal-pack.v1.json`                    |
+| `goal <intent>` / lifecycle options  | `.workspai/goals/index.json`                                | `workspai.goal-index.v1`                    | `contracts/workspace-intelligence/goal-index.v1.json`                   |
+| `goal --status/--list/... --json`    | stdout                                                      | `workspai.goal-lifecycle-result.v1`         | `contracts/workspace-intelligence/goal-lifecycle-result.v1.json`        |
 | `analyze`                            | `.workspai/reports/analyze-last-run.json`                   | `rapidkit-analyze-v1`                       | `contracts/analyze-last-run.v1.json`                                    |
 | `readiness`                          | `.workspai/reports/release-readiness-last-run.json`         | `release-readiness-v1`                      | `contracts/release-readiness.v1.json`                                   |
 | `pipeline`                           | `.workspai/reports/pipeline-last-run.json`                  | `rapidkit-pipeline-v1`                      | `contracts/pipeline-last-run.v1.json`                                   |

package/docs/contracts/COMMAND_OWNERSHIP_MATRIX.md

@@ -34,6 +34,7 @@ These commands are implemented and orchestrated by Workspai CLI:
 - `commands`
 - `create`
 - `goal`
+- `agent`
 - `project`
 - `shell activate`
 
@@ -58,6 +59,8 @@ These nested Commander commands are implemented and orchestrated by Workspai CLI
 - `product manifest`
 - `product manifest create`
 - `product plan`
+- `agent bootstrap`
+- `project agent-entry`
 - `project commands`
 - `project coverage`
 - `project archives`

package/docs/contracts/README.md

@@ -28,15 +28,28 @@ Canonical JSON lives in **`../../contracts/`** (CLI package root, published in t
 | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
 | `npm run generate:contracts`                | Regenerate runtime surface, create planner, agent customization pack, import-stack parity, module-layout, infra-stack |
 | `npm run check:generated-contracts`         | Verify committed JSON matches generators                                                                              |
-| `npm run sync:parity-snapshot`              | Copy canonical → vscode `contracts/` mirror                                                                           |
+| `npm run sync:shared-contracts`             | Generate canonical JSON and sync root plus locally available consumer mirrors                                          |
+| `npm run sync:parity-snapshot`              | Compatibility alias for canonical and consumer mirror synchronization                                                  |
 | `npm run check:parity-snapshot`             | Verify mirrors match canonical                                                                                        |
+| `npm run contracts:prepush`                 | Sync local consumers and require generated canonical CLI mirrors to be committed                                      |
 | `npm run validate:contracts`                | Shared-contract checks and focused contract tests                                                                     |
 | `npm run contracts:validate`                | Comprehensive generated/shared contract, parity, runtime-conformance, and adversarial gate                            |
 | `npm run check:agent-customization-drift`   | Verify generated agent customization files are committed in a consumer workspace                                      |
 | `npm run test:real-world -- ...`            | Qualify explicitly selected linked repositories in isolated or cumulative workspaces                                  |
 | `npm run test:real-world:enterprise -- ...` | Exercise the read-mostly, export, archive, agent dry-run, snapshot, and destructive dry-run command surface           |
 
-Workflow: change code → `npm run generate:contracts` → `npm run sync:parity-snapshot` → commit npm + vscode `contracts/`.
+Workflow: change code → `npm run sync:shared-contracts` → review and commit
+the CLI mirrors plus every locally available consumer mirror → push. When the
+VS Code repository is available, pre-commit synchronizes and stages its mirrored
+contracts. Pre-push refuses uncommitted canonical CLI outputs while consumer
+drift remains visible without coupling release cadence.
+
+The CLI does not require a cross-repository consumer workflow before npm
+publication. Workspai VS Code enforces hard parity in its own release CI against
+the CLI version it selects. Consumer-specific version floors remain owned by
+the consumer; schema synchronization never forces a redundant CLI release.
+Breaking schema changes are still blocked by versioned contract compatibility
+gates in the CLI.
 
 ## Documents in this folder
 
@@ -74,6 +87,8 @@ Published under `../../contracts/` (not duplicated in this folder):
 - `analyze-last-run.v1.json` — analyze evidence
 - `pipeline-last-run.v1.json` — governance pipeline orchestration
 - `project-entry-capability.v1.json` — open-ended adopt/import contract for readable projects
+- `workspace-intelligence/project-agent-entry.v1.json` — portable host discovery, canonical read order, authority boundaries, and integrity for an adopted project
+- `workspace-intelligence/agent-bootstrap-receipt.v1.json` — per-session proof of workspace membership, host coverage, schema validity, freshness, live inputs, and active Goal bindings
 - `adopt-effects.v1.json` — dry-run disclosure of project metadata, conditional repository-control reconciliation, and workspace operations before adoption
 - `create-planner-capabilities.v1.json` — native, official, and existing capability lanes
 - `agent-customization-pack.v1.json` — generated instructions, prompts, skills, agents, optional hooks, MCP-ready design metadata, target matrix, and drift state for AI agent surfaces
@@ -114,6 +129,11 @@ These schemas describe durable artifacts or bounded query results. A command's
 stdout may wrap an artifact with operation metadata such as `status`,
 `outputPath`, or a structured error; that envelope follows
 `cli-operation-result.v1.json` and does not change the nested artifact contract.
+`status: "success"` means the command completed and returned its contracted
+artifact; it does not override a policy gate. For gated operations such as
+`workspace verify --strict`, the envelope `exitCode`, process exit code, and
+nested gate exit code are identical even when the artifact was produced
+successfully and the gate blocked progression.
 
 CLI commands: see [commands-reference.md](../commands-reference.md) and the
 [CLI README](../../README.md#one-intelligence-chain).

package/docs/goal-packs.md

@@ -8,6 +8,12 @@ current Workspace Model and proof-backed Knowledge Graph.
 # Run inside an adopted project; scope defaults to that project.
 npx workspai goal "Raise test coverage to at least 85%"
 
+# Goals are not limited to coverage or another built-in metric.
+npx workspai goal "Add retry with exponential backoff for transient requests"
+npx workspai goal "Refactor the authentication boundary"
+npx workspai goal "Improve startup latency" --scope project:web
+npx workspai goal "Document the release workflow"
+
 # Plan for the whole canonical workspace.
 npx workspai goal "Prepare this workspace for release" --scope workspace
 
@@ -18,6 +24,13 @@ npx workspai goal "Map the authentication architecture" --dry-run --json
 The command plans work. It does **not** edit source, call a model, install an
 agent plugin, approve a repair, or claim that the outcome is complete.
 
+Goal intent is open-ended within the engineering workspace. The category is a
+retrieval and verification hint, not an allowlist. An objective that does not
+match the local deterministic classifier is retained as a low-confidence
+general Goal instead of being discarded; the original text remains the
+authority. Genuine compound ambiguity, missing numeric coverage targets,
+missing evidence, unsafe scope, or stale bindings still stop before mutation.
+
 ## What it produces
 
 A successful plan atomically publishes four portable artifacts:
@@ -68,10 +81,17 @@ npx workspai goal "Fix the authentication regression" --refresh --json
 
 The Goal Pack records both bindings and their exact hash semantics. The Model
 uses its stable structural projection; Graph and Goal artifacts use canonical
-JSON. A Goal fingerprint is an identity key and is never presented as a file
-digest. Regenerating after either source binding
-changes creates a different goal identity, preventing an agent from silently
-executing a proposal against stale architecture.
+JSON. The Graph binding also records its stable live-input fingerprint, so an
+evidence-only rerun does not make an unchanged Goal stale merely because the
+artifact timestamp changed. A Goal fingerprint is an identity key and is never
+presented as a file digest.
+
+The original source binding remains immutable. A later source state is accepted
+only when it is sealed by a Goal-bound, approved, closed CLI Repair transaction
+whose plan, proposal, checkpoint output, exact-target verification, canonical
+Model, Graph, and closure receipt all still validate. Any unlinked edit,
+post-closure edit, or unrelated workspace drift makes the Goal stale and
+requires a new Goal Pack.
 
 ## Honest preflight states
 
@@ -86,8 +106,16 @@ reported as `needs-evidence`, never as ready.
 selected intent and scope. Workspai refuses to hand broad source inspection to
 an agent until Workspace Intelligence is refreshed or the intent is clarified.
 
+Only a `ready-to-plan` Goal may become the active objective automatically.
+Planning a Goal that needs confirmation or evidence records it for review but
+does not replace the current active Goal.
+
 Preflight also carries the current Workspace Intelligence status, blocked
-stages, deterministic category queries, and bounded graph anchors.
+stages, objective-first retrieval queries, deterministic category recall, and
+bounded graph anchors. The complete user objective receives the primary anchor
+budget; generic category matches cannot crowd it out. When only structured
+category evidence is available, retrieval is reported as `partial`, not falsely
+as objective-grounded.
 
 ## Relationship to verified goals
 
@@ -118,6 +146,26 @@ completed verified goal clears the active selection. `--list` and `--cancel`
 remain available when an old Goal is stale, so operators can recover safely;
 `--status`, `--activate`, `--prepare`, and `--verify` require current bindings.
 
+The immutable Goal Pack also owns the execution-cycle budget. Every repair
+proposal is linked in the Goal index and every verification attempt is recorded
+in the verified-goal status artifact. Proposal planning and verification are
+serialized independently, refuse to exceed `executionPolicy.maxAttempts`, and
+remain bounded even when concurrent IDE or agent requests race. Consumers must
+restore both durable counters and use the greater value as the current cycle;
+they cannot reset a local retry counter. If the baseline already satisfies the
+criteria, the consumer should call the verifier immediately and avoid an
+unnecessary source change.
+
+Every other Goal is still executable through a compatible consumer, but its
+semantic outcome is not falsely presented as machine-verifiable. The consumer
+must assess the final diff or answer against the complete immutable objective,
+while the CLI independently owns scope, repair transactions, build/test/audit
+checks, canonical workspace verification, rollback, and the attempt budget.
+Such a result is evidence-reviewed; only the three exact producer contracts may
+use the lifecycle claim `verified`. Its `workspace-verify` success criterion and
+final orchestration step explicitly describe safety and evidence freshness; they
+never describe that signal as proof of an arbitrary semantic outcome.
+
 ## Ownership and safety boundary
 
 ```text
@@ -133,9 +181,22 @@ IDE chat, MCP, and future independent packages may render or transport it, but
 they cannot widen scope, grant network access, authorize mutation, mark a goal
 verified, or replace CLI evidence.
 
-Current Goal Packs use `proposal-only` mutation mode. Model-driven source
-proposal execution is intentionally a later bridge through the existing
-Repair Engine and, ultimately, the independent Decisions architecture.
+Current Goal Packs use `proposal-only` mutation mode: the CLI command itself
+does not invoke a model or mutate source. A compatible IDE or agent consumer
+may execute an inspected proposal only by submitting it to the existing CLI
+Repair Engine, binding the transaction to the active Goal fingerprint, and
+calling the exact Goal verifier after the transaction closes. A closed repair,
+generic test pass, or consumer message cannot mark the Goal verified. This
+boundary is designed to remain compatible with the independent Decisions
+architecture.
+
+Goal consumers must also preserve metric integrity. The Workspai extension does
+not expose file deletion to deterministic verified Goals. Its test-coverage
+Goal may write only test-owned source, fixtures, or snapshots; a general Goal
+may create, replace, or delete only inspected source through an approved,
+rollback-protected CLI Repair transaction. This prevents a model from reaching
+a numeric coverage target by shrinking or redefining the measured surface
+without crippling legitimate goals such as removing a deprecated module.
 
 ## Options
 
@@ -143,7 +204,7 @@ Repair Engine and, ultimately, the independent Decisions architecture.
 --workspace <path>      Explicit canonical workspace
 --scope <scope>         workspace or project:<name>
 --for-agent <consumer>  generic, claude, or codex (default: generic)
---max-attempts <count>  Bounded proposal budget, 1–25 (default: 5)
+--max-attempts <count>  Bounded execution-cycle budget, 1–25 (default: 5)
 --refresh               Refresh Workspace Intelligence before planning
 --dry-run               Validate and preview without writes
 --status [goal-id]       Validate active or named Goal bindings

package/docs/workspace-operations.md

@@ -54,8 +54,10 @@ npx workspai workspace import team.workspai-archive.zip --output ./team --json
 - Writes `.workspai/project.json`, `.workspai/adopt.json`, and `.workspai/adopt-readiness.json`.
 - Registry and contract sync include adopted projects for `workspace model`, `workspace context`, Dashboard, and agents.
 - Managed grounding writes a portable project lens, project grounding, and a
-  bounded managed section in `AGENTS.md`. User-authored `AGENTS.md` content is
-  preserved, and an authored tracked deletion of that file is never resurrected.
+  bounded managed section in `AGENTS.md`. It also publishes the portable agent
+  entry manifest and host adapters. User-authored instruction content and
+  symbolic links are preserved, and an authored tracked deletion is never
+  resurrected.
 - `--dry-run --json` previews detection without writing metadata. Its versioned
   `adoptedProject.effects` record also declares project metadata files,
   conditional `.gitignore`/`AGENTS.md` reconciliation, and the registration,
@@ -107,6 +109,7 @@ entry point into its canonical workspace:
 ```bash
 cd /absolute/path/to/project
 npx workspai project workspace status --json
+npx workspai agent bootstrap --for-agent codex --json
 npx workspai doctor workspace --json=summary
 npx workspai doctor project --json
 npx workspai workspace graph search "authentication endpoint" --limit 12 --json
@@ -121,12 +124,13 @@ one workspace silently when ownership is ambiguous.
 
 The project receives four distinct surfaces:
 
-| File                                           | Purpose                                                                       | Portable              |
-| ---------------------------------------------- | ----------------------------------------------------------------------------- | --------------------- |
-| `.workspai/workspace-link.local.json`          | Machine-local canonical workspace binding                                     | No; always gitignored |
-| `.workspai/reports/project-context-agent.json` | Bounded project view of model, graph, proofs, diagnostics, and safe commands  | Yes                   |
-| `.workspai/PROJECT-GROUNDING.md`               | Human- and agent-readable project entry guide                                 | Yes                   |
-| `AGENTS.md` managed section                    | Tells compatible agents where to start and when to cross the project boundary | Yes                   |
+| File                                           | Purpose                                                                        | Portable              |
+| ---------------------------------------------- | ------------------------------------------------------------------------------ | --------------------- |
+| `.workspai/workspace-link.local.json`          | Machine-local canonical workspace binding                                      | No; always gitignored |
+| `.workspai/agent-entry.v1.json`                | Versioned host coverage, read order, authority boundaries, and integrity proof | Yes                   |
+| `.workspai/reports/project-context-agent.json` | Bounded project view of model, graph, proofs, diagnostics, and safe commands   | Yes                   |
+| `.workspai/PROJECT-GROUNDING.md`               | Human- and agent-readable project entry guide                                  | Yes                   |
+| `AGENTS.md` and host adapters                  | Route supported hosts to the same canonical-first bootstrap                    | Yes                   |
 
 The bounded context includes project identity and commands, dependencies and
 dependents, related API/deployment/test surfaces, current project findings,
@@ -142,6 +146,10 @@ Mode reconciliation is convergent: changing modes removes stale managed
 sections, portable files, or ignore rules that the new mode no longer owns,
 while preserving user-authored `AGENTS.md` and `.gitignore` content.
 
+Run `project agent-entry verify --for-agent all --strict --json` to audit every
+host projection. See [Canonical-first agent entry](./agent-entry.md) for status,
+freshness, privacy, and consumer rules.
+
 If a workspace moved, or a cloned project has no valid local link, reconcile
 it explicitly: