@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/meeting-evidence-user-guide.md

@@ -0,0 +1,200 @@
+# Meeting evidence user guide
+
+Use Meeting evidence when you have meeting minutes or an existing transcript and want to turn useful statements into traceable project evidence without treating the conversation as automatic project truth.
+
+Ask EWAI: “Help me analyse these meeting notes and show the information we might use as project evidence.” Identify the local file and agree its classification and processing permission before analysis. EWAI uses the `ewai-meeting-evidence` skill to prepare proposed statements and source references. You review every proposal; a separate approval saves the accepted evidence. You don't need to construct the extraction contract yourself. The commands below let you inspect or repeat the individual steps.
+
+The workflow is **register → prepare → review → promote**. Each boundary is deliberate: registration records permission, preparation establishes safe processing and personas, review records a named human decision for every candidate, and promotion creates evidence only.
+
+## What you need
+
+- An initialised EWAI project.
+- A local `.md`, `.markdown`, `.txt`, `.text`, `.vtt` or `.srt` source.
+- Authority to process the material.
+- A classification and an explicit decision about hosted cloud processing.
+- A named reviewer and, later, a named evidence approver.
+
+Meeting evidence does not connect to Teams, Zoom or another meeting platform and does not transcribe audio or video. Export or prepare the source before using EWAI.
+
+## What the capability produces
+
+Meeting evidence does not import a transcript into the project knowledge base.
+It produces a reviewed evidence record that can be cited by later governed work.
+
+The workflow deliberately keeps three layers separate:
+
+1. **Private source registration** records the local path, classification,
+   processing policy and file digest in gitignored EWAI runtime state. This is
+   how EWAI can detect a changed or missing source without publishing its
+   contents.
+2. **Candidate and review state** records concise proposed observations,
+   interpretations, line anchors and the named review decision for every
+   candidate. Rejected and deferred material stays here rather than becoming
+   project evidence.
+3. **Promoted evidence** writes only accepted and amended statements, safe
+   provenance and integrity digests into paired Markdown and JSON files under
+   SPECS. The source text, absolute path and rejected statements are not copied
+   with them.
+
+This means a later intent, plan or decision can cite the meeting evidence while
+still showing where it came from and who accepted it. It does not mean the
+meeting has become unquestionable truth. A human must still reconcile the
+evidence with current product, stakeholder and repository evidence.
+
+## How personas participate
+
+Persona engagement is contextual rather than a fixed panel attached to every
+meeting. During preparation, EWAI starts with the standard host model and the
+relevant project and EWAI core personas. That baseline is complete and does not
+depend on a paid library.
+
+If premium or personal personas are already installed, EWAI can select relevant
+ones for specialist depth. For example, a Product Owner lens may identify an
+unresolved outcome, an Operator may expose a recovery concern, and a privacy
+specialist may flag a statement that should not be promoted without more
+evidence. Changing the source or focus replaces personas that are no longer
+relevant rather than accumulating an ever-growing panel.
+
+Every interface shows the personas currently engaged, including:
+
+- the persona name and tier: project, core, premium or personal;
+- the concern or signal that caused it to be selected;
+- why it is useful at this point in the workflow.
+
+Personas help propose questions, interpretations and candidate coverage. They
+cannot supply missing stakeholder evidence, decide that a statement is true,
+review their own candidates, accept risk, approve Manual QA or authorise a
+release. Those decisions remain with named people.
+
+## Ways to use it
+
+The same domain workflow is available through four surfaces:
+
+| Surface | Best used for | Important boundary |
+| --- | --- | --- |
+| CLI | Repeatable local operation, scripting and inspecting exact JSON results | Commands still require the same named review and promotion confirmation |
+| EWAI skill | Asking an AI host to analyse an allowed source and prepare schema-valid candidates | The skill cannot inspect denied or unknown cloud-processing material and cannot approve its own output |
+| MCP tools | Letting a compatible AI host register, prepare, review or promote through typed operations | The server owns the project root; callers cannot redirect operations to another folder |
+| Mind Palace | Human inspection of sources, provenance, dispositions and active personas | It never previews raw transcript content or silently calls a model |
+
+These are adapters over one evidence contract, not four different workflows.
+A candidate prepared through the skill can be inspected in Mind Palace and
+promoted through the CLI without changing its review or authority requirements.
+
+## 1. Register the source
+
+```bash
+ewai meeting register ./meeting-notes.txt \
+  --project . \
+  --label "Product review" \
+  --classification internal \
+  --cloud-processing allowed \
+  --yes \
+  --json
+```
+
+Choose `public`, `internal`, `confidential` or `restricted`. Set cloud processing to `allowed`, `denied` or `unknown`; never select `allowed` merely to make the workflow convenient.
+
+EWAI fingerprints the file and stores its absolute path in private gitignored runtime state. It does not copy raw meeting material into SPECS or return the path in public status data.
+
+## 2. Check processing permission and prepare analysis
+
+EWAI checks that the file hasn't changed and establishes what processing is allowed before the host analyses it. You'll see the source status and relevant persona perspectives. If you want to inspect preparation directly, run:
+
+```bash
+ewai meeting prepare <source-id> --project . --json
+```
+
+Preparation checks that the registered digest is current and returns:
+
+- whether hosted processing is permitted;
+- the strict candidate schema and line bounds;
+- safe source facts;
+- the active persona ensemble, including each name, tier, matched concern and engagement reason;
+- the human-authority boundary.
+
+See [how personas participate](#how-personas-participate) for selection and authority. Preparation never installs or updates a persona pack; changing the focus or source replaces the active ensemble.
+
+If processing is denied or unknown, the result names a manual local handoff. A hosted AI must not open the source.
+
+Preparation isn't a successful extraction: proposed statements come next, and none become evidence until reviewed and approved. The host's permitted source, output format and citation limits are defined in the [implementer guide](meeting-evidence-implementer-guide.md); you don't need to author that protocol to use the guided conversation.
+
+## 3. Review candidates
+
+An AI host using `$ewai-meeting-evidence` can prepare a candidate bundle. Each item separates a concise observed statement from interpretation and cites exact line anchors. Raw transcript excerpts are excluded.
+
+Review every candidate as `accepted`, `rejected`, `amended` or `deferred`. Amendments require replacement text and a rationale. Then record the complete named review:
+
+```bash
+ewai meeting review <source-id> \
+  --input ./meeting-review.json \
+  --reviewed-by "Product Owner" \
+  --project . \
+  --json
+```
+
+The input file contains both `bundle` and `dispositions`. Follow the [complete meeting-review example](examples/meeting-review.md) for the candidate schema, the registration ID/digest handoff and the files created after promotion.
+
+The input file must be inside the project. A persona cannot perform this review for you.
+
+## 4. Inspect in the Mind Palace
+
+Open the loopback dashboard, select **Mind Palace**, then choose the keyboard-reachable **Meeting evidence** mode.
+
+The source rail shows safe labels, classification, processing policy, digest freshness and counts. For each proposed statement, you can see where it came from in the meeting notes, how the reviewer treated it, and whether it was added to the saved evidence. The context rail always shows the active personas and their tiers. It never shows a raw transcript or absolute source path.
+
+“Prepare extraction” returns a contract to the dashboard; it does not call a model. “Promote accepted” appears only for a current, fully reviewed source.
+
+## 5. Promote evidence
+
+Check status first:
+
+```bash
+ewai meeting status <source-id> --project . --json
+```
+
+Then make a separate named decision:
+
+```bash
+ewai meeting promote <source-id> \
+  --project . \
+  --yes \
+  --approved-by "Product Owner" \
+  --json
+```
+
+Only accepted and amended candidates are written to paired files under the configured SPECS root at `3.Evidence/meeting-evidence/<source-id>/`. Rejected and deferred history remains in the private review record.
+
+The paired files serve different readers while representing the same accepted
+evidence set:
+
+- Markdown provides a readable provenance and review record for people.
+- JSON provides deterministic identifiers, anchors, digests and dispositions
+  for EWAI tooling.
+
+Promotion checks both the registered source digest and reviewed candidate
+digest before writing. If either changed, it stops instead of silently applying
+an old decision. The paired write is atomic, so an interrupted promotion cannot
+leave Markdown and JSON claiming different outcomes. Repeating an identical
+promotion returns the existing receipt rather than duplicating evidence.
+
+If your project uses [lifecycle hooks](using-lifecycle-hooks.md), promotion can notify them through `ewai.meeting-evidence.promoted`. The notification excludes transcript text, the source path and credentials. A hook failure doesn't undo the saved evidence; see the implementer guide for the event format.
+
+Promotion does not create a task, intent, requirement, process, policy, persona, architecture decision, Build approval, accepted risk, Manual QA result or release decision. Use the normal governed workflow if the evidence suggests downstream work.
+
+## When EWAI stops
+
+- **Source stale or missing:** register or review the current file; old review cannot be promoted.
+- **Processing denied or unknown:** use an approved local route; hosted inspection is blocked.
+- **Malformed candidates:** correct the candidate JSON; do not edit around validation.
+- **Incomplete review:** record one decision for every proposed statement: accept it, amend it, reject it or defer it.
+- **Conflicting evidence pair:** preserve it and investigate instead of overwriting it.
+- **Repeated identical promotion:** EWAI returns the existing result idempotently.
+
+Accepted meeting evidence can still be incomplete or wrong. Check the sources, interpretation and relevance before using it in a decision. If the notes raise security concerns, route them through [security validation](security-validation-guide.md); promoting the notes doesn't resolve those concerns.
+
+## Related guidance
+
+- [Working with personas](working-with-personas.md)
+- [Human approval and assurance](human-approval-and-assurance-guide.md)
+- [Meeting evidence implementer guide](meeting-evidence-implementer-guide.md)

package/Docs/operations/dashboard-and-delivery-state.md

@@ -0,0 +1,153 @@
+# Dashboard and delivery-state operations
+
+Use this guide to inspect EWAI work, understand which state is authoritative, and recover projections without editing phase status by hand.
+
+## Inspecting, queuing and doing work
+
+- **Inspect:** status views and `delivery continue` explain recorded progress and the next permitted step.
+- **Queue or hand off:** a supported dashboard action prepares work for the host to pick up.
+- **Execute:** the host performs the requested work through the appropriate skill and guarded operations.
+
+A queued handoff isn't a completed feature, and opening a view doesn't run its workflow. Follow the host's conversation and actual activity/results to see whether execution began.
+
+## Open the project dashboard
+
+Project check-in starts or reuses the local loopback dashboard and returns its actual URL:
+
+```bash
+ewai checkin --project .
+```
+
+You can also manage the server explicitly:
+
+```bash
+ewai server status --project .
+ewai server start --project .
+ewai server stop --project .
+```
+
+Use the returned URL rather than assuming a fixed port.
+
+## Choose the views you need
+
+The left sidebar keeps optional tools out of the way until you choose them. Open **Configuration**, select the views you need and save the changes. Portfolio, Team Hub, Governed Rollout, Starters, Policy Gates, Security Validation, Hooks, AI context diagnostics and Contributions all start hidden.
+
+Showing a view doesn't connect a service, run a security tool or approve a change. Hiding it doesn't disable a required check. See [Choose what's in your dashboard](dashboard-configuration.md) for the controls and command-line equivalents.
+
+## Understand the state layers
+
+| Layer | Purpose | Authority |
+| --- | --- | --- |
+| Intent Markdown | Human-readable purpose, journeys, acceptance, constraints, and relationships | Durable project truth |
+| Adjacent intent JSON | Structured companion state for the intent | Durable and must agree with Markdown |
+| `SPECS/6.Build/<slug>/delivery-state.json` | Canonical guarded phase, approval, validation, and run state | Durable delivery truth |
+| `.ewai-pipeline/data/pipeline.sqlite` | Fast dashboard and API projection | Rebuildable operational state |
+| Repository and Palace indexes | Search, graph, and knowledge-navigation projections | Rebuildable operational state |
+
+Do not “fix” a disagreement by editing the SQLite database or raw delivery status. Use audit and guarded transition commands.
+
+## Inspect delivery
+
+```bash
+ewai delivery status <intent-slug> --project . --json
+ewai delivery continue <intent-slug> --project . --json
+ewai delivery runs <intent-slug> --project . --json
+```
+
+`continue` reports the next action without starting it. It neither resumes work nor bypasses a gate. If work is shelf-ready, use the guarded resume operation rather than starting Build directly.
+
+## Read phase status accurately
+
+- **pending:** the stage has not started.
+- **running:** active work or a human gate is in progress.
+- **completed:** canonical artefacts and a passing hashed gate ledger were recorded.
+- **skipped:** the declared condition did not apply.
+- **not-supported:** a provider-gated stage could not run under the resolved policy.
+- **paused-awaiting-manual-qa:** automated Delivery is complete and human acceptance remains outstanding.
+- **blocked:** a declared issue prevents safe progress.
+
+Do not describe `not-supported` as passed or a running Manual QA gate as complete.
+
+## Four-way integrity
+
+Audit intent copies and delivery alignment:
+
+```bash
+ewai intent audit-state --project . --json
+```
+
+The audit can recreate a missing adjacent JSON sidecar from authoritative project records, but it reports disagreement rather than silently choosing between conflicting durable states.
+
+When drift appears:
+
+1. stop phase transitions;
+2. identify which durable file changed and why;
+3. compare with version-control history and the gate evidence;
+4. use a supported delivery or intent operation to reconcile it;
+5. refresh the dashboard projection;
+6. verify the audit is consistent before continuing.
+
+## Runs and live activity
+
+Command runs explain which host, mode, and phase initiated work. Live activity records material events such as handoffs, decisions, external reviews, responses, blockers, human questions, and completed artefacts.
+
+The activity stream shows material changes and decisions, not a token-by-token transcript or periodic “still working” messages. A quiet stream alone doesn't mean that work has stopped.
+
+If a command process ended without closing its run record, inspect before marking old records stale:
+
+```bash
+ewai delivery runs --mark-stale --hours 6 --project .
+```
+
+Do not mark a genuinely active long-running operation stale merely because it has been quiet.
+
+## Repository index operations
+
+```bash
+ewai index status --project . --json
+ewai index freshness --project . --json
+ewai index refresh --project . --json
+ewai index coverage --project . --json
+ewai index profiles --source organisation --project . --json
+ewai index files --outcome analysis_failed --project . --json
+ewai index search "authentication" --limit 20 --project .
+ewai index graph src/example.mjs --limit 20 --project .
+```
+
+Refresh before substantive source, Blast Radius, or standards claims when the map is missing or stale. Review outcomes and depths separately: a completed run inventories the supported project tree but does not mean every file was opened or deeply analysed. The **Impact** tab also shows active persona provenance; those perspectives are advisory and do not alter repository facts.
+
+## Mind Palace operations
+
+```bash
+ewai palace status --project . --json
+ewai palace refresh --project . --json
+ewai palace search "release decision" --limit 20 --project .
+ewai palace tidiness --project . --json
+ewai palace housekeeping --project .
+```
+
+The Palace indexes canonical SPECS sections. Housekeeping is review-led; it must not silently rewrite project knowledge.
+
+## Dashboard safety
+
+- Bind and use the project-local loopback service as configured.
+- Do not treat dashboard buttons as a weaker approval path; approval actions must create the same durable evidence.
+- Preserve unrelated work and host configuration during restarts.
+- Treat the dashboard as unavailable if you cannot confirm a healthy process and current URL.
+- A stale state file or port is diagnostic evidence, not proof that the service is running.
+
+## Related guides
+
+- [Developer delivery guide](../developer-delivery-guide.md)
+- [Troubleshooting and recovery](troubleshooting-and-recovery.md)
+- [CLI and configuration reference](../reference/cli-and-configuration.md)
+
+## Current contract sources
+
+- `src/runtime/dashboard.mjs`
+- `src/runtime/work.mjs`
+- `src/runtime/runs.mjs`
+- `src/runtime/repository-index.mjs`
+- `src/runtime/palace.mjs`
+- `src/delivery.mjs`
+- `src/intents.mjs`

package/Docs/operations/dashboard-configuration.md

@@ -0,0 +1,87 @@
+# Choose which dashboard views you need
+
+The dashboard starts with its everyday tools. Extra views are off by default, so you don't have to navigate portfolio management, policy controls or integration tools when your project doesn't need them.
+
+## Show an extra view
+
+1. Open your project's dashboard.
+2. Choose **Configuration** near the bottom of the left sidebar.
+3. Tick the views you need.
+4. Choose **Save changes**.
+5. Open the new item in the sidebar.
+
+You can turn a view off again in Configuration. That hides it; it doesn't delete its records or remove required checks.
+
+On a small screen, open the navigation drawer to reach Configuration. On a larger screen, **Collapse sidebar** gives the work area more room. That setting is saved for the project too.
+
+## What the optional views are for
+
+| View | Use it when you need to… | What you still need to set up |
+| --- | --- | --- |
+| **Portfolio** | Compare several local projects and their dependencies. | A project portfolio manifest. |
+| **Team Hub** | Share approved project summaries and reusable resources with your team. | A separately operated Hub and an explicitly approved connection. |
+| **Governed Rollout** | Review adoption and differences across configured projects or organisations. | The rollout's project and baseline configuration. |
+| **Starters** | Review and add your team's approved starter files. | An accepted starter receipt, target mappings and a reviewed source adapter. |
+| **Policy Gates** | Check proposed work against your organisation's configured design policies. | The applicable policy content and project configuration. |
+| **Security Validation** | Review configured security checks, findings and decisions. | Security profiles and the relevant external tools or adapters. |
+| **Hooks** | See whether a configured integration received an EWAI milestone. | A registered handler and an enabled event subscription. |
+| **AI context diagnostics** | Inspect which evidence and personas EWAI selected for an AI task. | A relevant task or context request to inspect. |
+| **Contributions** | Add business or technical context to work that's already in progress. | The relevant delivery and contribution context. |
+
+Turning on a view only makes it visible. It doesn't run a scan, connect a service, execute an integration or install anything.
+
+Similarly, hiding **Security Validation** or **Policy Gates** doesn't waive requirements already configured for the project.
+
+## If you're looking for an older name
+
+**Phase Studio** is now labelled **Contributions**.
+
+**Context Inspector** is now labelled **AI context diagnostics**.
+
+These are different tools. Contributions helps people add information to a delivery; AI context diagnostics helps you inspect what information is being supplied to an AI task.
+
+## Manage your persona licence
+
+In Configuration, find **Premium personas** and choose **Manage licence**. You can use this even when premium access is active and the setup prompts have disappeared from the sidebar.
+
+See [Set up and update premium personas](premium-personas-setup.md).
+
+## If settings won't save
+
+If the project configuration changed while you were editing it, refresh the settings before saving again. EWAI refuses to overwrite a newer configuration using an older copy.
+
+If the configuration can't be read, ask your technical owner to check the configured `pipeline.yaml`. Don't delete the file or replace its approval and standards sections to make the dashboard load.
+
+## Configure views from the CLI
+
+An AI assistant can help with the same settings through the dashboard-configuration flow. If you're scripting the change yourself, first read the current preferences:
+
+```bash
+ewai dashboard preferences --project . --json
+```
+
+Use the returned `digest` when saving. It identifies the configuration you inspected, so the command can reject a save if someone has changed it since.
+
+For example, to show Portfolio:
+
+```bash
+ewai dashboard configure --enable portfolio --expected-digest DIGEST --yes --project .
+```
+
+Replace `DIGEST` with the value returned by the first command. To hide it, use `--disable portfolio`. To change sidebar width, use `--collapse` or `--expand`.
+
+The technical view IDs are:
+
+| Display name | CLI ID |
+| --- | --- |
+| Portfolio | `portfolio` |
+| Team Hub | `team-hub` |
+| Governed Rollout | `rollout` |
+| Starters | `starters` |
+| Policy Gates | `policies` |
+| Security Validation | `security` |
+| Hooks | `hooks` |
+| AI context diagnostics | `context-inspector` |
+| Contributions | `phase-studio` |
+
+These preferences are stored in the project's configured `pipeline.yaml`. They aren't separate permissions, and they don't replace the setup instructions for the feature you've chosen.

package/Docs/operations/installation-updating-and-entitlements.md

@@ -0,0 +1,135 @@
+# Install and update EWAI
+
+EWAI is installed through npm. Your project's code and SPECS stay in your workspace; premium personas are an optional, separately licensed download.
+
+This guide covers the harness installation. For a persona licence, use [Set up and update premium personas](premium-personas-setup.md). For an existing codebase, follow [Existing-project onboarding](../existing-project-onboarding-guide.md) after installation.
+
+## Before you start
+
+You'll need Node.js 22.5 or newer, npm, Git for project version control, and a supported host: Codex, Claude Code or Google Antigravity's `agy` CLI. Technology packs can have further requirements.
+
+EWAI includes its own parsers. Don't add Tree-sitter dependencies to your application just to use the harness.
+
+## Install globally
+
+This makes `ewai` available from your project folders:
+
+```bash
+npm install --global @thebackstoryis/engineering-with-ai
+ewai install --host auto
+ewai
+```
+
+The installation command makes the host skills and MCP connection available. You can choose one host explicitly with `--host codex`, `--host claude` or `--host antigravity`.
+
+If npm returns `E404`, check the exact package name and configured registry first. That response alone doesn't tell you whether the package is unpublished, unavailable to your account or missing its requested version. If the intended package still isn't available, contact the publisher; don't install a similarly named package as a substitute.
+
+An authentication/access failure is also separate from a persona licence. Check npm's own error before changing account settings. Never enter a persona key in an npm command.
+
+### Keep the harness version with one project
+
+For a project-local development dependency:
+
+```bash
+npm install --save-dev @thebackstoryis/engineering-with-ai
+npx ewai install --project . --host auto
+npx ewai
+```
+
+Review and commit the package and lockfile changes through your normal project process.
+
+### Run without a global installation
+
+```bash
+npx --yes @thebackstoryis/engineering-with-ai@latest
+```
+
+This asks npm to obtain and run the package. It doesn't create a standing global installation.
+
+## Start your project
+
+Open your project folder in the host and start EWAI. Agree where its SPECS folder should live before initialising it. For existing code, EWAI offers Archaeology to reconstruct missing project knowledge; you can accept or decline it.
+
+For explicit terminal setup:
+
+```bash
+ewai init --project /path/to/project --name "Example Product" --codex
+ewai doctor --project /path/to/project --json
+```
+
+Initialisation preserves existing files unless you deliberately supply `--force`. Don't use that option to clear a setup error without inspecting what it would replace.
+
+A multi-repository workspace can keep SPECS separately:
+
+```bash
+ewai init \
+  --project /path/to/workspace \
+  --name "Example Product" \
+  --specs project-knowledge/SPECS \
+  --init-specs-repo
+```
+
+The locator in `.ewai-pipeline/project.json` records the chosen SPECS location.
+
+After initialisation, check that `.ewai-pipeline/project.json` points to your chosen SPECS folder and that the folder exists. Open the host conversation to complete Discovery; those files alone don't mean onboarding is finished. Follow [your first session](../tutorials/first-session.md) for the observable steps.
+
+## Update the harness
+
+Use the npm update action offered by EWAI's check-in. For a global installation, an explicit update is:
+
+```bash
+npm install --global @thebackstoryis/engineering-with-ai@latest
+ewai install --host auto
+```
+
+For a project dependency, update through its package manager and review the lockfile. Refresh the intended host installation afterwards.
+
+Start a fresh session and check that it reports the expected version. If the dashboard is still running an older runtime, use the [dashboard recovery instructions](troubleshooting-and-recovery.md#dashboard-will-not-start).
+
+A source checkout is for developing EWAI, not updating the installed harness. Pulling a repository doesn't update your npm installation.
+
+## Check that it's ready
+
+For a diagnostic report:
+
+```bash
+ewai checkin --project . --json
+ewai doctor --project . --json
+```
+
+Check the result for an actionable problem: a dashboard that didn't start, inconsistent project state, a missing tool or an update that needs your decision. An unavailable network check means EWAI couldn't establish that fact; it doesn't by itself mean your project or licence is broken.
+
+Check-in can start or reuse the dashboard, refresh derived state and check the persona licence. It doesn't automatically download persona updates. A confirmed expiry of the matching team licence can remove the unchanged managed pack; see [subscription expiry](premium-personas-setup.md#what-happens-when-annual-access-expires).
+
+## Where host configuration lives
+
+| Host | Project skills | Project MCP configuration |
+| --- | --- | --- |
+| Codex | `.agents/skills/` | `.codex/config.toml` |
+| Claude Code | `.claude/skills/` | `.mcp.json` |
+| Google Antigravity | `.agents/skills/` | `.agents/mcp_config.json` |
+
+EWAI merges its entries with unrelated host configuration. Don't replace the entire file to update one entry. After an update, check that your other MCP servers are still present.
+
+## Premium personas
+
+Enter your licence through **Configuration → Premium personas → Manage licence** in the dashboard, or use the hidden terminal prompt:
+
+```bash
+ewai persona premium configure --project .
+```
+
+Submitting a valid key verifies access, saves it privately and installs the pack immediately. Wait for the readiness confirmation before relying on it for analysis. Later updates need a separate decision; normal session checks don't download them.
+
+Your own personal and project personas aren't part of the managed pack. See the [setup guide](premium-personas-setup.md) for failures, updates and the difference between individual and team expiry. The [provider reference](../persona-entitlement-provider-guide.md) covers archive validation and storage for implementers.
+
+## Related guides
+
+- [Choose dashboard views](dashboard-configuration.md)
+- [Dashboard and delivery state](dashboard-and-delivery-state.md)
+- [Troubleshooting and recovery](troubleshooting-and-recovery.md)
+- [Working with personas](../working-with-personas.md)
+
+## Implementation references
+
+`src/install.mjs`, `src/project.mjs`, `src/checkin.mjs`, `src/persona-entitlements.mjs`, `src/runtime/mcp-config.mjs`, `tests/install.test.mjs` and `tests/checkin.test.mjs`.

package/Docs/operations/premium-personas-setup.md

@@ -0,0 +1,76 @@
+# Set up and update premium personas
+
+If you have a persona licence, you can enter it in the dashboard and install the pack straight away. You don't need to clone a repository or download files by hand.
+
+You can also keep using EWAI's core personas without a premium licence.
+
+## Enter your key
+
+Start EWAI in your project and open the dashboard link it gives you. If the project hasn't been set up yet, let EWAI create the agreed SPECS structure first.
+
+1. Open **Configuration** in the dashboard's left sidebar.
+2. Under **Premium personas**, choose **Manage licence**.
+3. Enter the key from your Conversational Coding account or team invitation.
+4. Submit the form. EWAI verifies the licence, saves it privately on your computer and downloads the pack.
+5. Wait for **Premium personas are ready**. The result includes the installed version and persona count.
+
+Submitting the key authorises that installation. You don't need a second download step after setup succeeds. The new personas can be used in the same session.
+
+The licence is stored in private user-level EWAI configuration, outside your project. Don't paste it into a chat, command argument or SPECS document.
+
+**Set up premium personas** may also appear in the sidebar when premium access isn't active. Once access is valid and the installed pack is verified, the learning and setup prompts disappear. **Configuration → Manage licence** remains available.
+
+### Prefer a terminal?
+
+In a genuine interactive terminal, run:
+
+```bash
+ewai persona premium configure --project .
+```
+
+Type the key into the hidden prompt. This also verifies and installs immediately. Don't add the key as a command-line argument or ask an AI assistant to collect it in chat.
+
+## Before analysing an existing codebase
+
+If you want premium perspectives included in Archaeology, finish setup before accepting that investigation. If setup fails, retry it or deliberately continue with core personas. Installing a pack later doesn't retroactively change an analysis that's already been completed.
+
+Archaeology itself is optional. You can decline it and return to it later.
+
+## Get later updates
+
+Each new session checks access and the available pack version. That check doesn't automatically download a new release.
+
+When EWAI offers an update, approve it if you want the new version. For an explicit terminal update:
+
+```bash
+ewai persona premium sync --project . --yes
+```
+
+EWAI checks the archive and its contents before replacing the installed pack. If the verified pack is already current, it doesn't download it again.
+
+Keep your own personas in your personal or project library, not in the managed premium cache. Updates shouldn't overwrite work you've created yourself; local edits inside the managed cache can instead block an update.
+
+## If setup doesn't finish
+
+| What happened | What to do |
+| --- | --- |
+| The key couldn't be verified | Copy it again from your account or invitation. Check your connection and retry. An unavailable service isn't proof that your key is invalid. |
+| The licence was saved, but the pack wasn't installed | Retry setup when the connection is available. The saved key and the installed pack are separate: saving the key alone doesn't mean the personas are ready. |
+| Installation finished, but readiness couldn't be confirmed | Don't treat that as a successful setup. Retry verification or choose to continue with core personas. |
+| The service reports the three-machine limit | Review the machines in My Account and deactivate one you no longer use before retrying. |
+| EWAI reports local changes in the premium cache | Preserve and inspect those changes. Don't force an update over them or delete the cache as a first response. |
+| The installed pack belongs to a different seat | Review which licence and pack you intend to use. Replacement needs an explicit decision; it isn't a routine update. |
+
+For detailed storage, replacement and validation behaviour, use the [provider reference](../persona-entitlement-provider-guide.md). Its implementation detail is separate from this setup path.
+
+## What happens when annual access expires?
+
+**Individual subscription:** you can keep using the installed personas. You no longer receive updates or new downloads after access expires.
+
+**Team subscription:** when the service confirms expiry for the matching team seat, EWAI stops using that managed pack and removes it if safe to do so. If the files have been modified or safe cleanup is blocked, it preserves them for investigation but excludes the expired pack from persona selection.
+
+Your personal and project personas aren't part of that cleanup.
+
+A failed connection or an unverified response isn't confirmed expiry and mustn't trigger deletion. However, a team expiry already confirmed earlier remains in effect during a later outage.
+
+This matters even when you're only checking status: a licence check can enforce confirmed team expiry. It isn't an unconditional “read-only” operation.