@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/operations/troubleshooting-and-recovery.md

@@ -0,0 +1,205 @@
+# Troubleshooting and recovery
+
+Use this guide when EWAI cannot check in, find project state, open the dashboard, resolve a pack or persona, or move a delivery forward.
+
+## Protect work before diagnosis
+
+First establish:
+
+- the exact project root and current branch;
+- tracked, modified, staged, and untracked files;
+- whether another agent or person is working in the same checkout;
+- the configured SPECS root;
+- whether the failing action could overwrite or delete material.
+
+Do not auto-stash, reset, clean, or delete runtime directories as a first response. Unrelated changes belong to their owner.
+
+## Collect a diagnostic baseline
+
+```bash
+ewai checkin --project . --json
+ewai doctor --project . --json
+ewai intent audit-state --project . --json
+ewai server status --project .
+ewai index freshness --project . --json
+ewai palace status --project . --json
+```
+
+These commands aren't all read-only. Check-in can start or reuse the dashboard and refresh derived state; `intent audit-state` can recreate missing intent sidecars. Persona licence checks can enforce confirmed matching team expiry. If you only need to inspect a running server or index, use those individual status commands first.
+
+Record unknown checks and their reasons. A network failure, missing CLI, stale projection, and invalid durable state require different recoveries.
+
+## Project cannot be found
+
+Check for:
+
+- `.ewai-pipeline/project.json` in the workspace or an ancestor;
+- `SPECS/pipeline.yaml` at the configured location;
+- a Git root if the project was expected to resolve from Git;
+- a moved workspace with stale absolute runtime references;
+- running the command from an unrelated directory.
+
+Supply `--project /exact/path` when discovery is ambiguous. Do not create a second SPECS tree just because the expected one was not found.
+
+## Check-in reports state drift
+
+Four records must remain aligned: intent Markdown, adjacent intent JSON, delivery state, and the rebuildable SQLite projection.
+
+Recovery:
+
+1. stop delivery actions;
+2. inspect `ewai intent audit-state --project . --json`;
+3. compare durable files with Git history and recent approved actions;
+4. preserve the most recent human-authored intent content;
+5. use canonical intent or delivery operations to repair state;
+6. rerun check-in and the audit;
+7. resume only after consistency is restored.
+
+Never edit SQLite directly. Never invent a completed gate or approval.
+
+## Dashboard will not start
+
+```bash
+ewai server status --project .
+ewai server stop --project .
+ewai server start --project .
+```
+
+Use the current returned URL. If restart fails, inspect the reported process and log paths, port ownership, Node version, and filesystem permissions. Preserve logs needed for diagnosis before any cleanup.
+
+## Repository index is stale or partial
+
+```bash
+ewai index freshness --project . --json
+ewai index refresh --project . --json
+ewai index status --project . --json
+ewai index coverage --project . --json
+ewai index profiles --project . --json
+ewai index files --outcome analysis_failed --project . --json
+```
+
+Report `analysed`, `inventory_only`, `skipped_sensitive`, `skipped_oversized`, and `analysis_failed` separately, then review deep, shallow, and inventory depths. If freshness reports `profile-catalogue-changed`, inspect active packs and profiles before refreshing. Unsupported, malformed, sensitive, or oversized files remain visible without making the whole run unusable; limit source claims to the verified coverage. See the [Repository Source Map guide](../repository-source-map-guide.md).
+
+## Delivery will not continue
+
+```bash
+ewai delivery status <intent-slug> --project . --json
+ewai delivery continue <intent-slug> --project . --json
+```
+
+Common causes:
+
+- **Completing Intent is blocked because the intent is still draft:** agree its outcome and acceptance criteria and make it ready through the intent workflow. A draft can begin delivery; it can't finish the Intent stage;
+- a required canonical artefact is missing;
+- gate evidence changed after completion;
+- the task graph is invalid or task evidence incomplete;
+- Build approval has not been recorded;
+- a provider validation cycle is unfinished;
+- the delivery is shelf-ready and requires resume/FitCheck;
+- Manual QA is awaiting a person;
+- durable state copies disagree.
+
+These commands inspect progress; they don't ask the host to perform the next stage. Continue in the EWAI conversation once the reported blocker is resolved.
+
+Compare [the two amendment operations](../completed-phase-evidence-amendments.md#which-amendment-operation) before changing completed evidence.
+
+When a named human has approved legitimate amendments and the current phase is Build, use the guarded recovery rather than editing stored hashes:
+
+```bash
+ewai delivery ratify-amendments <intent-slug> \
+  --project . \
+  --yes \
+  --approved-by "Owner" \
+  --scope "Exact amended evidence being ratified"
+```
+
+This operation validates all completed phase artefacts and ledgers, records their previous and replacement hashes, and does not grant Build approval. Follow the reported next action. Do not change `currentPhase`, gate status, hashes, or completion percentages by hand.
+
+## Premium persona sync fails
+
+Read the actual failure before retrying. Licence verification, archive download and local validation are different steps.
+
+- **Key rejected:** copy it from My Account or the team invitation and retry the private setup form.
+- **Key saved, download failed:** retry setup when the connection is available; the key alone doesn't make the pack ready.
+- **Local files changed:** preserve those edits before deciding how to recover the managed library.
+- **Different seat or provider:** confirm which subscription should own the installation; replacement requires explicit consent.
+- **Archive rejected:** preserve the previous pack and report the validation error. Don't unpack it manually to bypass the check.
+- **Interrupted operation or held lock:** check whether another installation is running before investigating its staging files. Don't delete a live lock.
+
+Persona downloads come from the website, not Git. See [Set up and update premium personas](premium-personas-setup.md) for the full recovery path.
+
+## A persona is missing or irrelevant
+
+```bash
+ewai persona path --scope project --project .
+ewai persona list --project . --query <topic>
+```
+
+Check valid frontmatter, scope, ID, description, tags, capabilities, and project root. If the persona appears but is not engaged, its metadata may not match the section. Improve the complete owned persona; do not rely on automatic overlay composition.
+
+## A Blueprint is rejected
+
+Diagnose root discovery, strict manifest parsing, compatibility, dependencies, content paths, size limits, digest, preview revision, and destination conflicts in that order. Use [Blueprint validation and troubleshooting](../blueprints/validation-and-troubleshooting.md).
+
+## A Governed Starter Pack cannot be prepared or applied
+
+Start with the safe workspace:
+
+```bash
+ewai starter status --project . --json
+ewai starter adapters --project . --json
+```
+
+Check, in order:
+
+1. the Organisation Blueprint receipt is still accepted and has not drifted;
+2. every logical target has one non-overlapping `starter_materialisation.targets` mapping;
+3. every configured repository is its own Git working-tree root;
+4. the registered adapter package, publisher, version, entrypoint, and package digest have not drifted;
+5. the adapter supports the receipt's source class and writes every file beneath exactly one target source path;
+6. the independently verified aggregate staged-tree digest matches the receipt;
+7. the preview is unexpired and repository revisions are unchanged;
+8. every destination remains `create` or `identical`, with no conflict or protected path.
+
+Prepare a fresh preview after any legitimate change. Never edit the runtime SQLite rows, preview digest, journal, classification, or evidence by hand.
+
+If application reports `recovery-required`, inspect the preserved paths and obtain human direction before changing them. Recovery is digest-sensitive:
+
+```bash
+ewai starter recover <attempt-id> --project . --yes --json
+```
+
+EWAI removes only unchanged files it can prove it created and empty directories it journalled. A changed file is preserved. Do not delete it merely to clear the state. See [Governed Starter-Project Materialisation](../governed-starter-project-materialisation-guide.md).
+
+## Recovery requires destructive action
+
+Stop and obtain explicit authority when recovery would:
+
+- delete or overwrite project knowledge;
+- remove a managed cache or runtime database;
+- discard Git changes;
+- replace host configuration;
+- force an update or rewrite history;
+- affect another project or user.
+
+Resolve exact targets with read-only checks and prefer recoverable operations. After any authorised material deletion, record what was removed and how it can be recovered.
+
+## Diagnostic handoff template
+
+Record:
+
+- project root and configured SPECS root;
+- branch and worktree state without secret content;
+- EWAI version and installation source;
+- exact command and error;
+- check-in, doctor, integrity, dashboard, and index status;
+- last known successful action;
+- durable files involved;
+- actions already attempted;
+- the decision or authority now required.
+
+## Related guides
+
+- [Installation, updating, and entitlements](installation-updating-and-entitlements.md)
+- [Dashboard and delivery state](dashboard-and-delivery-state.md)
+- [Developer delivery guide](../developer-delivery-guide.md)

package/Docs/organisation-rollout-guide.md

@@ -0,0 +1,142 @@
+# Organisation rollout guide
+
+Use this guide to introduce EWAI across several teams while keeping organisational consistency, project autonomy, and human accountability in balance.
+
+## Recommended practice
+
+EWAI supports project-local configuration, shared Blueprints and personas, delivery checks, an optional [Team Hub](team-hub-guide.md) and [Governed Rollout views](consultancy-network-rollout-control-plane-guide.md). Your organisation operates and configures the shared services; installing EWAI doesn't connect a project to them automatically.
+
+The staged adoption model below is recommended practice, not a mandatory rollout enforced by the software.
+
+## Start with an operating agreement
+
+Before selecting tools or packs, agree:
+
+- the problems EWAI is expected to reduce;
+- which decisions remain with Product Owners, engineers, governance, and platform teams;
+- the minimum Definition of Ready and Definition of Done;
+- evidence and retention expectations;
+- permitted AI hosts and data classifications;
+- independent validation expectations;
+- how exceptions are requested and reviewed;
+- who owns shared Blueprints, standards, and personas.
+
+Measure adoption by better decisions and safer outcomes, not the number of generated artefacts.
+
+## Choose proportionate adoption levels
+
+| Level | Suitable starting point |
+| --- | --- |
+| Foundation | One stakeholder perspective, one engineering lens, shared ready/done definitions, independent review, and one learning per delivery |
+| Team | Project SPECS, contextual personas, repository index, guarded delivery, standards sweep, and Manual QA |
+| Organisation | Reviewed Blueprint Packs, organisation personas, catalogue governance, versioning, rollout communication, and assurance reporting |
+
+These level names describe an adoption plan, not selectable runtime modes. There isn't a `Foundation` switch that disables required gates. Configure the capabilities your teams need; accepted standards and the active delivery's required checks still apply.
+
+Teams can stop at the depth their risk and maturity justify. Do not require every advanced artefact for every small change.
+
+## Pilot before mandating
+
+Select a small set of contrasting projects:
+
+- one new internal tool;
+- one existing system with knowledge gaps;
+- one user-visible feature;
+- one higher-assurance or sensitive workflow.
+
+For each pilot, capture baseline cycle time, rework, escaped issues, onboarding effort, approval delay, and participant confidence. Add qualitative evidence about whether the method improved shared understanding.
+
+## Build the organisation baseline
+
+Use an [Organisation Blueprint Pack](designing-organisation-blueprint-packs.md) only for reviewed defaults that genuinely apply across its declared audience. Separate:
+
+- mandatory organisation standards;
+- optional modules for particular risk or technology contexts;
+- organisation-specific persona templates;
+- reference-only boilerplates;
+- project decisions that must remain local.
+
+Create a documented owner, review cadence, compatibility policy, and deprecation path before broad use.
+
+## Preserve project autonomy
+
+A project should be able to explain:
+
+- which Blueprint version and modules it accepted;
+- what was materialised into project truth;
+- what local standards or personas were added;
+- what exceptions were approved and why;
+- whether an upstream update has been reviewed;
+- who owns the resulting project decisions.
+
+The organisation publishes a baseline. The project owner accepts the consequences.
+
+## Develop organisation personas carefully
+
+Organisation-specific personas should encapsulate a useful professional perspective—such as the organisation's architecture or API approach—without impersonating a real person or becoming a hidden policy store.
+
+Use [Creating organisation-specific personas](personas/organisation-specific-personas.md) and [Persona governance](personas/persona-governance.md). Keep mandatory rules in standards, and use personas to ask context-sensitive questions about those rules.
+
+## Establish a change process
+
+For each shared release:
+
+1. state the reason and affected audience;
+2. classify breaking, additive, corrective, or deprecating changes;
+3. validate the pack and its bounded content;
+4. compare outputs against representative pilot projects;
+5. publish provenance, version, compatibility, digest, and release notes;
+6. communicate required project action;
+7. allow projects to review before adopting;
+8. monitor outcomes and record learning.
+
+Never silently rewrite existing project truth from a changed upstream pack.
+
+## Support non-technical teams
+
+Offer colleagues a facilitated session through Guided Discovery rather than requiring everyone to use the terminal. Discovery shows its active personas and their reasons; use that information to discuss missing perspectives with the group. Explain technical consequences in plain language and involve the same authorised human approvers as in a CLI-based review.
+
+See the [non-technical team guide](adoption/non-technical-team-guide.md).
+
+## Governance without central bottlenecks
+
+Central teams should own shared contracts and assurance expectations, not every project decision. A scalable model separates:
+
+- **publisher ownership:** shared pack and standard quality;
+- **project ownership:** local outcomes and adoption decisions;
+- **delivery ownership:** implementation evidence and engineering quality;
+- **governance ownership:** risk thresholds, exceptions, and auditability;
+- **platform ownership:** installation, runtime health, and supported integrations.
+
+## Measures worth tracking
+
+Recommended measures include:
+
+- time from idea to ready intent;
+- decisions reopened because evidence was missing;
+- onboarding time for inherited systems;
+- standards exceptions by reason;
+- defects found before and after Manual QA;
+- percentage of shared updates deliberately reviewed;
+- project and stakeholder confidence;
+- reusable learning incorporated into standards or guides.
+
+Avoid league tables based solely on AI usage, token volume, or artefact count.
+
+## Rollout checklist
+
+- [ ] Operating agreement and ownership model approved.
+- [ ] Data and AI-host boundaries understood.
+- [ ] Pilot portfolio selected and baselines recorded.
+- [ ] Shared standards, personas, and Blueprints have named owners.
+- [ ] Projects retain explicit adoption and exception decisions.
+- [ ] Non-technical participation is supported.
+- [ ] Update, deprecation, recovery, and assurance routes are documented.
+- [ ] Measures assess outcomes and learning rather than activity.
+
+## Related guides
+
+- [Internal Blueprint catalogue](blueprints/internal-blueprint-catalogue.md)
+- [Maintaining Organisation Blueprints](blueprints/maintaining-organisation-blueprints.md)
+- [Governance team guide](governance/governance-team-guide.md)
+- [Consultancy and multi-project rollout](adoption/consultancy-and-multi-project-rollout.md)

package/Docs/persona-entitlement-provider-guide.md

@@ -0,0 +1,199 @@
+# Persona entitlement and pack providers
+
+EWAI distributes premium personas separately from the public framework package. Distribution is website-only: this guide explains licence-checked Easy Digital Downloads (EDD)/WordPress delivery and the independent local verification controls.
+
+Premium personas are optional advisory lenses. Core and project personas, together with the standard host model, remain a complete baseline. Entitlement does not engage a persona, and a persona does not acquire approval authority.
+
+This is the integration reference. If you just want to enter a key or update your pack, start with [Set up and update premium personas](operations/premium-personas-setup.md).
+
+
+<!-- editorial: contents -->
+## On this page
+
+- [Keep four states separate](#keep-four-states-separate)
+- [Inspect safe status](#inspect-safe-status)
+- [Install, repair, or update](#install-repair-or-update)
+- [Pack contract](#pack-contract)
+- [Verification receipts](#verification-receipts)
+- [Website provider: wordpress-edd](#website-provider-wordpress-edd)
+- [This is governance, not DRM](#this-is-governance-not-drm)
+- [Provider implementation checklist](#provider-implementation-checklist)
+- [Troubleshooting](#troubleshooting)
+- [Related guides](#related-guides)
+- [Contract sources](#contract-sources)
+
+## Keep four states separate
+
+| Question | Meaning | Evidence |
+| --- | --- | --- |
+| Is the user entitled? | The configured provider currently permits acquisition. | Provider access result. |
+| Is the pack installed? | A local managed pack directory exists. | Local filesystem state. |
+| Is the pack verified? | The current files, source, revision, manifest, and external receipt agree. | Core validation plus receipt. |
+| Is a persona active? | The current workflow selected an installed persona as a relevant lens. | The workflow's active-persona ensemble. |
+
+These states must never be collapsed into one `premium: true` flag. In particular, a verified local installation may still be useful during a temporary provider outage, while an entitled user may choose not to install it.
+
+## Inspect safe status
+
+Run the status command (it never downloads; confirmed matching team expiry can perform the cleanup described below):
+
+```bash
+ewai persona premium status --project . --json
+```
+
+The `ewai.persona-entitlement/v1` result includes the provider, access classification, local status, installed and verified flags, compatibility, safe revision and digest metadata, an optional action, and a conditional upgrade URL. It intentionally omits credentials, raw provider responses, absolute cache paths, pack contents, and persona bodies.
+
+Access has three values:
+
+- `available`: the provider confirmed access to the configured pack revision;
+- `unavailable`: authenticated status confirms that the subscription no longer grants access;
+- `unknown`: connectivity or another unclassified failure prevented a trustworthy conclusion.
+
+Unknown is not denied access. It must not trigger an upsell. A purchase link is available when no key is configured or authenticated status confirms unavailable access, and no local pack is installed.
+
+Local status is one of:
+
+- `not-installed`;
+- `installed-unverified`;
+- `installed-not-remotely-verified`;
+- `current`;
+- `update-available`.
+
+The action may instead report `blocked-local-changes`. Do not force or merge a managed cache in that state.
+
+## Install, repair, or update
+
+First-time licence submission in the dashboard or interactive `persona premium configure` calls `configureAndInstallPremiumPersonas`: activation, private credential storage, download, validation and readiness confirmation happen in that operation. Submitting the key authorises installation. A saved key with a failed download isn't a ready pack.
+
+Status and normal check-in never download premium content. After the user explicitly agrees to the offered action, run:
+
+```bash
+ewai persona premium sync --project . --yes
+```
+
+If a matching verified pack is already current, sync reports that without downloading again. Otherwise it acquires an immutable archive into `.ewai/packs/.staging/`, verifies the advertised SHA-256 and byte size, validates ZIP paths and the manifest version, and independently validates the content. It then moves the existing pack to a temporary backup, promotes the candidate atomically, writes the receipt, and removes the backup. If promotion or receipt writing fails, it restores the previous installation and receipt.
+
+The `--yes` option is a command confirmation, not a standing entitlement or approval. Automation must not add it unless a person has explicitly authorised that particular install, repair, or update.
+
+## Pack contract
+
+The minimal persona-only manifest in `pack.yaml` is:
+
+```yaml
+schema: ewai.persona-pack/v1
+id: ewai.personas.professional
+version: 1.0.0
+content:
+  personas: premium-personas
+```
+
+The minimal format's schema is published at `config/persona-pack.schema.json`. The canonical premium source library instead uses the richer `ewai.pack/v1` persona manifest. The runtime supports that source-compatibility format only for `type: persona`, the expected id/version/content, and allowlisted inert name, description, commercial, source, updates, compatibility and normalisation metadata. Boilerplates must be absent or empty; commands, skills and deployment fields are rejected. This compatibility adapter does not expand the minimal JSON schema or execute pack metadata.
+
+CCE archives include the customer reference `docs/model-selection.md` and `manifest.json`, the commerce release manifest. Its schema is `ewai.persona-pack/v1` and it counts personas by collection. The client requires pack.yaml version to match the advertised immutable release. For maintainers testing both sides of delivery—not ordinary pack users or independent client implementers—the joint integration test builds and server-validates the actual dual-manifest archive, then installs identical bytes. This optional test uses `EWAI_CCE_PLUGIN_ROOT` or the sibling checkout and PHP ZipArchive; self-contained npm tests explicitly skip that joint test when those dependencies are unavailable.
+
+### Legacy compatibility, not the authoring format
+
+New releases should use the current full manifest above. Compatibility identifies older installed content; it isn't a recommendation to publish missing identity/version metadata.
+
+During transition, a legacy manifest without `schema`, `id`, and `version` remains compatible when it declares `content.personas`; status reports that as `compatible-legacy` rather than pretending it is current.
+
+Core validation applies regardless of provider:
+
+- the declared persona directory must be a safe relative path inside the candidate;
+- symbolic links and special files are rejected;
+- only Markdown, text, YAML, JSON, CSV, and recognised extensionless notice files are accepted;
+- no file may exceed 1 MiB;
+- a pack may contain at most 1,000 files and 16 MiB in total;
+- the declared persona directory must contain at least one file;
+- the deterministic SHA-256 digest covers every accepted relative path, size, and file body in stable order.
+
+These bounds make validation predictable and stop a persona pack from becoming an unbounded executable or binary delivery channel.
+
+## Verification receipts
+
+A downloaded archive is not trusted merely because the server accepted a licence. EWAI writes a separate `ewai.persona-pack-receipt/v1` receipt beneath the local `.ewai/packs/.receipts/` directory. It records:
+
+- pack and provider IDs;
+- manifest version and compatibility mode;
+- exact source revision;
+- deterministic content digest;
+- verification time.
+
+Status revalidates the current pack and compares it with the receipt. Editing a persona, replacing the source, changing revision, or altering the receipt makes the installation unverified. The receipt lives outside the pack so a candidate cannot provide its own evidence of trust.
+
+## Website provider: `wordpress-edd`
+
+Use `ewai persona premium configure --project .` in an interactive terminal. The hidden prompt verifies the key and registers this installation before writing owner-private `~/.ewai/entitlements/conversational-coding.json`, then downloads and verifies the pack immediately. This EWAI config stores the key and activation token for later session check-ins; no credential enters project YAML, Git, SPECS or safe dashboard output.
+
+Machine identity is a random 64-hex installation secret in owner-private `~/.config/conversational-coding/installation.json`, schema `cce.installation/v1`, field `installationSecret`. EWAI and Monomyth clients must reuse that secret on the same machine, rather than hashing a hostname or copying the file to another machine. Machine name is a display label. A seat supports three machines. Deactivate old machines in My Account. Monomyth integration itself is deferred to its own build.
+
+The website provider is the default even before key setup. Missing credentials offer the private terminal prompt without a network request and never block core EWAI use. Project persona configuration accepts only `provider: wordpress-edd` and an optional server; obsolete source fields and raw licence fields are rejected. Existing unsupported caches stay untouched and excluded until safely replaced through an explicitly owned recovery. The default server is `https://www.conversationalcoding.dev`. A separately approved self-hosted origin can be supplied during setup; never use a different origin as an authentication-failure fallback.
+
+Each check-in and dashboard launch performs fresh authenticated status, including reuse of a server; check-in shares one promise with its dashboard launch. Status contains the immutable current manifest/version. Launches never request a grant or archive. When offered an update, obtain consent before sync. Cross-seat/provider replacement additionally requires `--replace`.
+
+The REST contract uses activation, bearer-authenticated status and download-grants under `/wp-json/conversational-coding/v1/persona-pack`. Grants return same-origin `/?cce-download=...` URLs. Credential-bearing requests never follow redirects. JSON is capped at 64 KiB, archives at 20 MiB; streams time out. The immutable archive size and SHA-256 must match the release; ZIP entries are bounded before writing and pack validation remains independent. Website revision is its archive SHA-256, not a Git commit. pack.yaml version must match the current release. No source repository is queried or cloned for persona delivery.
+
+The external receipt additionally records safe provenance: server, subscription ID, seat ID and plan type. Atomic promotion/receipt rollback and exclusive mutation locking protect the active cache. Interrupted operations may leave a lock/staging directory needing investigation; no timer silently steals an active lock.
+
+### Expiry is not a generic error
+
+The updated CCE authenticated status supplies subscription id, `plan_type`, explicit `status`, `ends_at`, seat ID and activation ID. The client requires those fields and a consistent unavailable/expired result before expiry handling. Older/malformed contracts produce uncertainty and preserve files.
+
+Confirmed team expiry removes **only** the managed premium cache and receipt matching that server/subscription/seat/team plan. A key from another seat cannot delete an individually supplied pack. An expired individual subscription retains its installed personas and reports that updates have ended. No new download is permitted. Cancellation keeps access for the remainder of the paid term. Refunded/revoked/inactive status does not invent an expiry purge policy. There is no invented offline deletion deadline.
+
+Personal `~/.ewai/personas` and authored project personas are never scanned or mutated by cleanup. Unknown access, invalid activation, arbitrary 403, timeout and outage never trigger deletion. Unsafe paths/symlinks or a concurrent mutation block cleanup visibly.
+
+Locally changed team content is preserved rather than erased. A known-expiry block is recorded in an independent private `persona-access-denial.json` projection before acquiring the pack mutation lock, then in the receipt when safe cleanup can proceed. The denial binds to that installed receipt generation, server, subscription and seat; it cannot follow a fresh authenticated replacement pack. The shared premium catalogue path becomes unavailable, so CLI, dashboard and persona selectors cannot engage the retained expired team pack, including while another mutation holds the lock. That confirmed block survives a later outage. A valid renewed matching subscription can explicitly install a fresh verified pack to restore access; individual receipts are never blocked by this team rule. Filesystem failures that prevent safe denial recording or deletion require an explicit stop and manual investigation, not a successful-cleanup claim.
+
+For a deployment acceptance test, verify an individual purchase, an allocated team seat, the three-machine limit and archive delivery against that deployment. A passing local fixture test isn't evidence that a particular live server has been configured correctly.
+
+## This is governance, not DRM
+
+The mechanism does not provide DRM and cannot guarantee that an authorised recipient will never copy files. Its purpose is to keep commercial content out of the public package, make authorised acquisition explicit, record local provenance, detect drift, and avoid accidental disclosure through product surfaces.
+
+Entitlement status is operational evidence. It does not approve Build, cannot approve Manual QA, certify persona quality, accept licence terms on someone's behalf, or replace a commercial system of record.
+
+## Provider implementation checklist
+
+Before enabling another provider, verify:
+
+- all three access outcomes are deterministic and tested;
+- safe output has no credential, raw response, absolute path, or pack-body leakage;
+- check-in/status never download; only authenticated matching team expiry may remove managed content;
+- sync still requires explicit human consent;
+- acquisition is confined to core-supplied staging;
+- the common validator and receipt writer cannot be bypassed;
+- failed validation and failed promotion preserve the previous verified installation;
+- concurrent or interrupted operations cannot produce a half-promoted pack;
+- an upgrade link appears only for known unavailable access without an installation;
+- legacy compatibility is visible rather than silently upgraded;
+- full package and npm dry-run tests include the adapter without including commercial persona content.
+
+## Troubleshooting
+
+| Status or symptom | Meaning | Safe response |
+| --- | --- | --- |
+| `access: unknown` | The provider could not be classified reliably. | Preserve any verified local pack and retry later. |
+| `installed-unverified` | Local content and its receipt do not agree. | Do not use it as trusted premium content; offer governed repair when access is available. |
+| `installed-not-remotely-verified` | Local validation passes, but current entitlement or freshness is unknown. | Keep the verified local state visible and avoid claiming it is current. |
+| `blocked-local-changes` | The managed cache is dirty or has another origin. | Preserve it for investigation; never force-sync over it. |
+| Candidate rejected | Release digest/size, grant origin, ZIP path/file limits, CRC, manifest version or content validation failed. | Keep the prior pack and report the bounded reason. |
+| Receipt drift | Current files no longer match verified provenance. | Treat the installation as unverified and reacquire only after explicit consent. |
+
+## Related guides
+
+- [Installation, updating, and entitlements](operations/installation-updating-and-entitlements.md)
+- [Working with personas](working-with-personas.md)
+- [Human approval and assurance](human-approval-and-assurance-guide.md)
+- [Troubleshooting and recovery](operations/troubleshooting-and-recovery.md)
+
+## Contract sources
+
+- [src/persona-entitlements.mjs](../src/persona-entitlements.mjs)
+- [src/checkin.mjs](../src/checkin.mjs)
+- [src/cli.mjs](../src/cli.mjs)
+- [src/runtime/dashboard-server.mjs](../src/runtime/dashboard-server.mjs)
+- [config/persona-pack.schema.json](../config/persona-pack.schema.json)
+- [config/project.schema.json](../config/project.schema.json)
+- `tests/persona-entitlements.test.mjs`
+- `tests/persona-entitlement-package.test.mjs`