@enterpriseai/cli 3.19.0 → 3.19.2

package/resources/gofer/references/agent-catalog.json

@@ -0,0 +1,126 @@
+{
+  "schemaVersion": 1,
+  "stages": [
+    "0_gofer_start",
+    "0a_problem_validation",
+    "1_gofer_research",
+    "2_gofer_specify",
+    "3_gofer_plan",
+    "4_gofer_tasks",
+    "5_gofer_implement",
+    "6_gofer_validate",
+    "7_gofer_save",
+    "7a_stakeholder_comms",
+    "8_gofer_branding",
+    "9_gofer_tests",
+    "10_gofer_cloud",
+    "gofer_constitution",
+    "gofer_hydrate",
+    "gofer:bootstrap-workspace",
+    "gofer:check-workspace",
+    "gofer:diagnose",
+    "gofer:eai-first-run",
+    "gofer:personality",
+    "gofer:plan",
+    "gofer:side",
+    "gofer:spec-summary",
+    "gofer:tdd",
+    "gofer:vocabulary",
+    "gofer:zoom-out"
+  ],
+  "surfaces": [
+    {
+      "id": "claude",
+      "legacy": false,
+      "evidenceKind": "self-declaration",
+      "independentReadIsolation": "unqualified",
+      "independentExecution": "unqualified"
+    },
+    {
+      "id": "codex",
+      "legacy": false,
+      "evidenceKind": "self-declaration",
+      "independentReadIsolation": "unqualified",
+      "independentExecution": "unqualified"
+    },
+    {
+      "id": "copilot",
+      "legacy": false,
+      "evidenceKind": "self-declaration",
+      "independentReadIsolation": "unqualified",
+      "independentExecution": "unqualified"
+    },
+    {
+      "id": "vscode",
+      "legacy": false,
+      "evidenceKind": "self-declaration",
+      "independentReadIsolation": "unqualified",
+      "independentExecution": "unqualified"
+    },
+    {
+      "id": "grok",
+      "legacy": false,
+      "evidenceKind": "self-declaration",
+      "independentReadIsolation": "unqualified",
+      "independentExecution": "unqualified"
+    },
+    {
+      "id": "antigravity",
+      "legacy": false,
+      "evidenceKind": "self-declaration",
+      "independentReadIsolation": "unqualified",
+      "independentExecution": "unqualified"
+    },
+    {
+      "id": "gemini",
+      "legacy": true,
+      "evidenceKind": "self-declaration",
+      "independentReadIsolation": "unqualified",
+      "independentExecution": "unqualified"
+    }
+  ],
+  "roles": [
+    { "id": "assumption-tracker", "body": "agents/assumption-tracker.md" },
+    { "id": "business-metrics-analyzer", "body": "agents/business-metrics-analyzer.md" },
+    { "id": "business-problem-validator", "body": "agents/business-problem-validator.md" },
+    { "id": "codebase-analyzer", "body": "agents/codebase-analyzer.md" },
+    { "id": "codebase-locator", "body": "agents/codebase-locator.md" },
+    { "id": "codebase-pattern-finder", "body": "agents/codebase-pattern-finder.md" },
+    { "id": "comms-writer", "body": "agents/comms-writer.md" },
+    { "id": "engineer-review", "body": "agents/engineer-review.md" },
+    { "id": "implement-bug-triangulator", "body": "agents/implement-bug-triangulator.md" },
+    { "id": "implement-code-review-council", "body": "agents/implement-code-review-council.md" },
+    { "id": "implement-doc-writer", "body": "agents/implement-doc-writer.md" },
+    { "id": "implement-error-hardener", "body": "agents/implement-error-hardener.md" },
+    { "id": "implement-performance-explorer", "body": "agents/implement-performance-explorer.md" },
+    { "id": "implement-test-diversifier", "body": "agents/implement-test-diversifier.md" },
+    { "id": "implement-variant-generator", "body": "agents/implement-variant-generator.md" },
+    { "id": "multi-perspective-judge", "body": "agents/multi-perspective-judge.md" },
+    { "id": "plan-api-comparator", "body": "agents/plan-api-comparator.md" },
+    { "id": "plan-architecture-diverger", "body": "agents/plan-architecture-diverger.md" },
+    { "id": "plan-data-model-stress-tester", "body": "agents/plan-data-model-stress-tester.md" },
+    { "id": "plan-migration-path-finder", "body": "agents/plan-migration-path-finder.md" },
+    { "id": "plan-refactor-rewrite-advisor", "body": "agents/plan-refactor-rewrite-advisor.md" },
+    { "id": "research-dependency-evaluator", "body": "agents/research-dependency-evaluator.md" },
+    { "id": "research-horizon-scanner", "body": "agents/research-horizon-scanner.md" },
+    { "id": "research-market-scanner", "body": "agents/research-market-scanner.md" },
+    { "id": "research-perspective-multiplier", "body": "agents/research-perspective-multiplier.md" },
+    { "id": "scope-creep-detector", "body": "agents/scope-creep-detector.md" },
+    { "id": "specify-ambiguity-detector", "body": "agents/specify-ambiguity-detector.md" },
+    { "id": "specify-journey-stress-tester", "body": "agents/specify-journey-stress-tester.md" },
+    { "id": "tasks-cross-cutting-scanner", "body": "agents/tasks-cross-cutting-scanner.md" },
+    { "id": "tasks-rollback-planner", "body": "agents/tasks-rollback-planner.md" },
+    { "id": "validate-security-red-team", "body": "agents/validate-security-red-team.md" },
+    { "id": "validation-correctness", "body": "agents/validation-correctness.md" },
+    { "id": "validation-integration", "body": "agents/validation-integration.md" },
+    { "id": "validation-performance", "body": "agents/validation-performance.md" },
+    { "id": "validation-security", "body": "agents/validation-security.md" },
+    { "id": "validation-standards", "body": "agents/validation-standards.md" },
+    { "id": "validation-test-quality", "body": "agents/validation-test-quality.md" },
+    { "id": "visual-bounded-context-writer", "body": "agents/visual-bounded-context-writer.md" },
+    { "id": "visual-c4-writer", "body": "agents/visual-c4-writer.md" },
+    { "id": "visual-erd-writer", "body": "agents/visual-erd-writer.md" },
+    { "id": "visual-heatmap-writer", "body": "agents/visual-heatmap-writer.md" },
+    { "id": "visual-risk-writer", "body": "agents/visual-risk-writer.md" }
+  ]
+}

package/resources/gofer/references/blocker-mediation.md

@@ -0,0 +1,156 @@
+# Blocker Mediation
+
+Technical escalation now requires a fresh diagnosis in the ask event's
+`verification` file. Use `priority-outcome-protection.md` for its required
+fields. A real business decision needs no failed command. Existing retry
+budgets, ask-once history and permissions remain unchanged.
+
+Keep the agreed goal. Stop spending time when progress needs an answer, access
+or a change outside the current work.
+
+## When To Use It
+
+Before retrying a failed action or asking for missing input, check the existing
+record. Routine successful work needs no blocker entry.
+
+Use the private feature directory for app or product delivery. For
+conversation-only work, reuse a private session directory. Do not initialise an
+app for a question. Share the directory when changing coding tools. Do not store
+passwords, access tokens or customer details in the record.
+
+## State And Actions
+
+Run
+`node .specify/scripts/node/gofer-blocker-control.mjs --state-dir <directory>`
+to inspect. Add `--task T001` only after confirming that task does not depend on
+blocked work. No task filter means the whole feature.
+
+Send actions with `--event <private-json-file>`. Reserve an action before asking
+the user or starting a tool. Exit code 1 means stop that action. The helper
+records decisions; it does not run commands or prove that permission was
+granted.
+
+| Action   | Effect                                                                                                  |
+| -------- | ------------------------------------------------------------------------------------------------------- |
+| open     | Record the cause and affected tasks. Repeated opens retain history and widen, never narrow, task scope. |
+| ask      | Reserve one question. Later attempts to ask again are denied.                                           |
+| attempt  | Reserve one investigation, then at most one different recovery.                                         |
+| result   | Record the reserved attempt's actual result. Progress alone does not mean resolved.                     |
+| classify | Update the cause without clearing a wait or resetting the budget.                                       |
+| resume   | Accept changed evidence and allow one further bounded investigation/recovery cycle.                     |
+| resolve  | Accept the relevant successful check or genuine answer as resolution evidence.                          |
+
+Use stable keys for the goal, affected subject and missing condition. Search the
+register before assigning keys. Do not derive them from question wording, model
+identity or command text. This identity rule needs agent judgement; the helper
+does not detect semantic aliases.
+
+An open event has this shape:
+
+```json
+{
+  "action": "open",
+  "goalKey": "feature-access",
+  "subjectKey": "workspace-selection",
+  "conditionKey": "user-choice-required",
+  "category": "decision",
+  "owner": "user",
+  "question": "Which workspace should this app use?",
+  "requiredChange": "The user selects the target workspace.",
+  "tasks": ["T001"]
+}
+```
+
+Categories are `decision`, `access`, `external`, `capability`, `solvable` and
+`unknown`. The first four start in a waiting state. An empty task list affects
+the whole feature. Other events use the returned `blockerId`. An `attempt` also
+needs a stable `approachKey`. A `result` needs the returned `attemptId`, a
+`summary` and `result`: `progress`, `no_progress` or `blocked`.
+
+## Evidence And Resumption
+
+For `resume` or `resolve`, supply `evidence` as a relative path inside the state
+directory. A resume also needs `category`: `solvable` or `unknown`. Keep
+evidence immutable:
+
+```json
+{
+  "blockerId": "<returned blocker ID>",
+  "kind": "change",
+  "result": "changed",
+  "source": "<actual user reply or external check reference>",
+  "summary": "<what changed and why work can proceed>"
+}
+```
+
+Resolution uses `kind: resolution` and `result: pass`. Cite a real answer for a
+decision, or the relevant successful check for a technical fault. A login answer
+does not prove app access. Record the check that the current scope requires.
+Local MVPs do not gain new authentication requirements from this rule.
+
+Missing, changed, reused or unrelated evidence is rejected. The helper checks
+its identity and file hash. It cannot authenticate a user reply or verify the
+truth of a hand-written receipt. The agent must inspect the referenced evidence
+and respect host permissions.
+
+One evidence-backed resumption is allowed. Existing lower time, token, retry and
+permission limits still apply. If that allowance is exhausted, stop for human
+review. Do not delete the record or invent a new goal. Repeated calls,
+unanswered questions and unchanged status are not progress.
+
+A pending attempt survives a restart. Inspect what actually happened before
+recording its outcome; never launch it again solely because the chat ended. A
+writer lock prevents simultaneous state changes. If a lock remains after a
+crash, confirm that no writer is active before manual recovery. Do not
+automatically delete it.
+
+## User Update
+
+For a status, blocker, low-confidence review, or decision, use these five labels
+so the reader can act without asking for a translation:
+
+```text
+Recommendation: Continue, reconcile, or wait.
+Why: State the verified rule or evidence that supports the recommendation.
+Next step: Name one concrete action.
+Owner: Name the verified person or role responsible; do not guess.
+User action: Required — <one exact action>, or Not required.
+```
+
+Keep the stop rule separate from its cause. A low-confidence result explains why
+Gofer held the task (the score did not meet the configured threshold); it does
+not explain why Jev chose that score. Choice probabilities identify the closest
+alternative only. Do not present them as Jev's reason. If the API returns no
+reason, say that the cause is unknown. Distinguish a missing or oversized input,
+a local budget hold, a provider error, and a review conflict when evidence shows
+which one occurred. Never report a provider 400 cause as known unless a safe
+diagnostic field establishes it.
+
+Report independent gates separately. State each gate's effect on the current
+goal and name its owner only when known. A Jev result does not approve CI,
+reviews, security, deployment, or release. Do not make confidence-only holds
+advisory or change the threshold without explicit approval. Continue safe
+evidence review rather than asking the user to approve an unexplained override.
+
+Run the response format check for these replies with
+`node .specify/scripts/node/gofer-response-check.mjs --input <private-draft-file> --kind answer --business-update`.
+The check verifies required labels and basic writing rules. It cannot verify
+that the explanation is true or the named owner is correct.
+
+State the result, business impact and one next action:
+
+> The page opens, but sign-in still fails. Access is needed to check the account
+> settings. This work is paused until access is available. The page layout can
+> continue separately.
+
+Ask the actual question once. Later progress updates must not repeat it. Waiting
+is not feature completion.
+
+## Validation Coverage
+
+Strict loop checks reject unresolved or invalid recorded blockers. Legacy
+features without a register retain their existing checks; absence is not proof
+that no blocker exists. Package tests must execute the helper, test restart
+behaviour, and verify all generated surface instructions. Native chat compliance
+needs separate host tests. These instructions cannot force an unsupported host
+to intercept every action.

package/resources/gofer/references/business-updates-and-goal-checks.md

@@ -0,0 +1,109 @@
+# Clear Updates And Current Goals
+
+## Business Replies
+
+Explain what changed, why it matters, and what happens next. Use two or three
+short sentences for progress. Do not repeat an unchanged update. State blockers
+and uncertainty without hiding them behind technical terms.
+
+Before sending, store the draft in a private local file and run:
+
+```sh
+node .specify/scripts/node/gofer-response-check.mjs --input <private-draft-file>
+```
+
+Use `--kind answer` for a full answer. Use `--previous <private-file>` to check
+for an identical progress update. Use `--technical` only when the user asks for
+technical detail. It is not a way to bypass a failed business reply. Rewrite
+failed drafts; do not send the findings instead of explaining the work. Do not
+commit drafts. The helper does not print the draft or previous reply.
+
+The check flags a bounded set of jargon, length, repetition, and long sentences.
+It does not prove meaning, technical accuracy, business clarity, or ASD-STE100
+conformance. A human or model review must still check those points. It cannot
+block chat messages sent directly by the coding app. Native tool logs remain the
+host's responsibility. Never claim universal message interception.
+
+## Reconcile Each Work Batch
+
+1. Read the agreed goal, current spec, tasks, and latest findings before work.
+2. Select tasks linked to that goal. Run the applicable acceptance checks.
+3. After learning something new, record the evidence and affected assumptions.
+4. Update the spec, plan, tasks, traceability, and validation scope as needed.
+   Record why a document remains valid if no change is needed.
+5. If the outcome, scope, cost, security, or delivery promise changes, ask the
+   user before accepting that change. Do not rewrite requirements to excuse
+   failing code. Preserve requirement IDs and the decision history.
+6. Mark tasks complete only after their checks pass. Record failure or blockage
+   instead of completion. Reopen affected tasks when evidence becomes stale.
+7. Explain the business effect. Continue the next authorized batch or report the
+   exact unresolved decision. Do not wait until final validation to reconcile.
+
+This applies to app and non-app features. Conversation-only requests need no
+feature files. Maintenance commands stay maintenance-only. Keep local MVP
+exemptions: no forced sign-in or deployment if the current scope excludes them.
+
+## Delivery Checkpoint
+
+New loop contracts enable `requireDeliveryCheckpoint: true` by default. For an
+existing feature with a spec and tasks, enable it in `loop-contract.json`. Do
+not disable it to hide a failed check. Create or reconcile `spec.md`, `plan.md`,
+`tasks.md`, and `traceability.md` first. Research-only work before that point
+does not need placeholder implementation artifacts. Legacy loop audits report
+that the new coverage is absent until it is enabled; they retain their existing
+checks.
+
+After checks pass, write a local JSON evidence record for each completed task:
+
+```json
+{
+  "result": "pass",
+  "check": "The actual executed acceptance check or named manual verification",
+  "requirements": ["FR-001"],
+  "specHash": "SHA-256 of the spec used by that check"
+}
+```
+
+Keep actual command output or manual verification records alongside it. Do not
+manufacture a passing record. Record evidence at test time; changing its spec
+hash later is not a valid way to reuse stale results. Evidence records and the
+mapping below are relative to the feature directory. Each traceability row must
+link the task to its requirement IDs.
+
+```json
+{
+  "T001": { "requirements": ["FR-001"], "evidence": "evidence/t001.json" }
+}
+```
+
+Capture the reviewed state with that mapping file:
+
+```sh
+node .specify/scripts/node/gofer-delivery-check.mjs --feature-dir <feature-dir> --capture --evidence-map <mapping-file>
+```
+
+An empty mapping is valid only when no tasks are complete. Capture stores
+hashes; it does not mark tasks complete or approve changed goals. Do not
+recapture solely to hide drift. Review the change, update affected documents,
+rerun checks, and replace stale evidence first.
+
+Before advancing a batch, resuming work, or claiming completion, run:
+
+```sh
+node .specify/scripts/node/gofer-delivery-check.mjs --feature-dir <feature-dir>
+```
+
+The existing strict loop audit also runs this check from the tasks stage when
+enabled or when a checkpoint exists. A failure blocks that audit. It checks
+document freshness and recorded task evidence. It does not independently execute
+acceptance tests, detect every code change, or prove semantic goal alignment.
+Keep the existing goal, test, browser, review, and release checks.
+
+## Supported Surfaces
+
+Claude, Codex, Copilot, VS Code, Grok, and Google command/skill packages receive
+the same rules and portable Node helpers through the existing build paths.
+Package tests prove the files are present. Script tests prove the checker
+behavior. Neither proves that a live desktop or CLI session called the helper.
+If the host cannot execute it, report the check as unverified; do not invent a
+pass.

package/resources/gofer/references/delivery-lineage.md

@@ -0,0 +1,48 @@
+# Customer Delivery Lineage
+
+Every active feature maintains `.specify/specs/{feature}/delivery-lineage.json`
+using schema `eai.delivery_lineage.v1`. The manifest is the machine-readable
+graph consumed by the documentation viewer; Markdown remains the human-readable
+evidence.
+
+Gofer operates in the customer trust plane. The graph must use `plane: customer`
+and may contain only `customer` and `public-contract` visibility. Never give the
+viewer a larger internal graph and rely on the UI to hide nodes.
+
+## PublicAPI Boundary
+
+EAI dependencies terminate at a published capability node:
+
+- kind: `public-api-capability`
+- visibility: `public-contract`
+- capability ID: `eai.publicapi.capability.{name}.v{major}`
+- source repository: `PublicAPI`
+- source path and commit: from the published capability contract
+
+Do not name or reference services, repositories, policies, infrastructure, or
+documentation behind PublicAPI. Customer projections must reject AdminAPI,
+ResourceAPI, Configurator, Authz, AzureAPI, AICore, GeoService, Infra2025,
+`eai-testing-dev`, `tech-docs`, personal absolute paths, and repositories not on
+the explicit export allowlist.
+
+## Stage Updates
+
+| Stage            | Required lineage update                                                                                       |
+| ---------------- | ------------------------------------------------------------------------------------------------------------- |
+| Start / Research | Customer need, research artifacts, owners, public capabilities, and evidence links                            |
+| Specify          | Requirements, acceptance outcomes, and the research evidence that supports or constrains them                 |
+| Plan             | Customer architecture, explicit decisions, concise rationale summaries, approvers, and PublicAPI dependencies |
+| Tasks            | Work-order nodes and links from requirements and decisions                                                    |
+| Implement        | Actual customer code, documentation, and test files changed                                                   |
+| Validate         | Planned-versus-actual reconciliation, test/outcome links, and honest current/suspect/broken/superseded status |
+
+Each source location must use a repository-relative path and should include an
+exact Markdown anchor, Git commit, and SHA-256 content hash when known. Record
+the decision, considered options, concise rationale, evidence, owner, and
+approval; never record hidden chain-of-thought.
+
+Use `.specify/templates/delivery-lineage-template.json` when the feature does
+not have a manifest. Preserve existing IDs and history when updating it. The
+headless `validateDeliveryLineage`, `projectCustomerDeliveryLineage`, and
+`serializeDeliveryLineage` contracts are authoritative for integrity,
+fail-closed customer projection, and deterministic output.

package/resources/gofer/references/mvp-capability-validation.md

@@ -0,0 +1,102 @@
+# MVP Capability-Based Validation Contract
+
+## Purpose
+
+Validate the work that the active feature specification requires now. Do not
+apply later delivery requirements to an early MVP.
+
+## Capability States
+
+Use one state for every relevant capability:
+
+| State            | Meaning                                                                | Validation result                                     |
+| ---------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
+| `not_applicable` | The feature does not require this capability.                          | Excluded from the result.                             |
+| `planned`        | The feature includes this capability, but no code exists.              | Visible as planned. It does not fail the current MVP. |
+| `implemented`    | Code or configuration exists.                                          | Evidence is required before completion.               |
+| `verified`       | Required evidence passes.                                              | Complete for the current feature scope.               |
+| `blocked`        | The active feature requires this capability, but evidence cannot pass. | The affected outcome is not complete.                 |
+
+## Required Gates
+
+1. Create `.specify/specs/{feature}/` before app or operator-tool source work.
+2. Map every specified requirement to an automated test, smoke check, or named
+   manual check.
+3. Validate only capabilities that are `implemented` or required by the current
+   delivery decision.
+4. Store HTTP checks, screenshots, and manual review evidence in the feature
+   validation report.
+5. State the exact feature result. Do not call an app working when a required
+   journey fails.
+
+## Conditional Gates
+
+| Capability                      | Required when                                                                                                     | Not required when                                          |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| EAI CLI and workspace readiness | The current feature uses EAI Platform services or the user asks to prepare an EAI deployment.                     | Local MVP work does not use EAI services yet.              |
+| EAI app template readiness      | The feature creates, changes, or validates an EAI Platform app integration.                                       | The local MVP has not entered EAI integration scope.       |
+| Authentication journey          | The specification includes sign-in, protected content, user roles, or a deployment target that requires identity. | Authentication is explicitly out of the current MVP scope. |
+| Deployment evidence             | The user asks to deploy or the feature claims a deployed outcome.                                                 | Local development and preview only.                        |
+| Browser preview evidence        | The feature changes user-facing behaviour.                                                                        | Non-app work or no user-facing change.                     |
+
+## Authentication Journey
+
+When authentication is `implemented`, `required`, or `blocked`, record these
+checks:
+
+1. Provider endpoint responds as expected.
+2. Callback address matches the configured provider value.
+3. Sign-in completes.
+4. A session exists.
+5. The first protected API call succeeds for an authorised user.
+6. An unauthorised user fails safely.
+
+Use `.specify/references/platform/eai-auth-access.md` for the access decision.
+Record owner confirmation of `workspace-only` (default) or explicitly approved
+`platform-authenticated` access. Test non-members, cross-workspace requests,
+revocation, and unavailable membership checks. Sign-in alone is not permission.
+Client SSO is a separate choice. Changing the provider must not widen access.
+Require a real federated journey before claiming that SSO is verified.
+
+If authentication is `not_applicable` or `planned`, record that state and the
+trigger that will make it required. Do not report an authentication failure.
+
+## Direction Changes
+
+Before work continues after a scope change:
+
+1. Update `spec.md`, `plan.md`, `tasks.md`, `traceability.md`, and the active
+   validation scope.
+2. Record the change, business effect, new capability state, and test impact.
+3. Tell the user what changed, what remains valid, and what now needs evidence.
+4. Re-open only the affected pipeline loop.
+
+## Completion Language
+
+Use one of these truthful statements:
+
+- `The current MVP works for its specified local journey.`
+- `The server runs. Authentication is not in the current MVP scope.`
+- `The server runs. Authentication is required and currently blocked.`
+- `The deployed journey is not verified because browser evidence is unavailable.`
+
+`run.sh`, `run.bat`, and `run.ps1` prove that the app starts. They do not prove
+authentication, sessions, EAI access, or deployment readiness.
+
+## Release Capability Ledger
+
+For a feature that claims a release or deployed outcome, create
+`release-capability-ledger.md`. Record every accepted capability with:
+
+| Field                   | Required evidence                                              |
+| ----------------------- | -------------------------------------------------------------- |
+| Business requirement    | Requirement ID and plain-language outcome.                     |
+| Acceptance evidence     | Automated test, smoke check, or named manual check.            |
+| Responsible change      | PR number and commit.                                          |
+| Required release branch | Branch or release candidate that must contain the commit.      |
+| Deployed evidence       | Browser, API, or operational evidence for the claimed outcome. |
+
+Final validation must not report a complete or 100% result when a required
+capability is missing from the specification or traceability record, remains on
+an open PR, is absent from the release branch, or lacks required browser
+evidence.

package/resources/gofer/references/platform/README.md

@@ -14,4 +14,4 @@ Core files:
 
 These files are intentionally public-safe. Private repositories can replace or
 extend them with organization-specific references, but Gofer should always be
-able to fall back to this pack without exposing secrets or workspace-private data.
+able to fall back to this pack without exposing secrets or tenant-private data.

package/resources/gofer/references/platform/eai-app-template.md

@@ -1,7 +1,7 @@
 # EAI App Template Reference
 
-Use `https://github.com/eai-support/eai-app-template` as the canonical public app
-template for EnterpriseAI app-delivery work.
+Use `https://github.com/eai-support/eai-app-template` as the canonical public
+app template for EnterpriseAI app-delivery work.
 
 ## Source Of Truth
 
@@ -19,10 +19,13 @@ template for EnterpriseAI app-delivery work.
 
 1. Browser code calls the local app BFF at `/api/eai/...`.
 2. Browser streaming uses `/api/eai/stream/...`.
-3. The BFF or server helpers attach auth, workspace, and correlation headers.
+3. For workspace-scoped PublicAPI calls, the BFF or server helpers forward the
+   `tenant` and `X-Tenant-Id` headers from server-validated workspace context,
+   and attach auth and correlation headers.
 4. The frontend never receives direct downstream database, blob, search, or
    PublicAPI credentials.
-5. Use PublicAPI V4 surfaces for direct platform calls.
+5. Use the published PublicAPI route family through the template SDK, named
+   `eai` commands, or an approved server-side helper.
 
 ## Implementation Contract
 
@@ -52,10 +55,9 @@ files, restore files automatically, or weaken protected EAI controls to pass.
 Local-only and customer-owned source retain their own validation paths.
 
 - Use Object Types as the data model contract.
-- Keep the PascalCase model `name` distinct from the exact lowercase
-  kebab-case stored `slug`. Emitted `linkTypes[].targetObjectType`, runtime
-  `target_type`, paths, resource commands, and governed v4 fields use exact
-  stored slugs. Never re-derive historical stored slugs.
+- Keep PascalCase model names separate from the exact stored `slug`. Use
+  lowercase kebab-case slugs in runtime paths and links; never re-derive or
+  rename a historical stored slug.
 - Use the template SDK and hooks for resources, documents, and chat.
 - Use config slots with `{ components: [...] }`, not stale array-only slot
   examples.
@@ -64,11 +66,11 @@ Local-only and customer-owned source retain their own validation paths.
 - Use the CLI for setup and verification:
   - `eai login`
   - `eai workspace select <workspace-slug>`
-  - `eai types validate`
-  - `eai types diff --tenant-key <key> --tenant-id <workspace-id>`
-  - `eai types seed --tenant-key <key> --tenant-id <workspace-id>`
-  - `eai resources schema --tenant-id <workspace-id>`
-  - `eai verify calls --tenant-id <workspace-id> --resource-type <object-type-slug>`
+  - `eai types validate --tenant-key <key> --tenant-id <tenant-id>`
+  - `eai types seed --tenant-key <key> --tenant-id <tenant-id>`
+  - `eai types diff --tenant-key <key> --tenant-id <tenant-id>`
+  - `eai resources schema --tenant-id <tenant-id>`
+  - `eai verify calls --tenant-id <tenant-id> --resource-type <type>`
 
 Do not describe retired templates as canonical scaffolds. The surviving public
 scaffold is the EAI App Template.