@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/context-aware-delivery-companion-guide.md

@@ -0,0 +1,198 @@
+# Context-Aware Delivery Companion
+
+This reference is for integration authors and engineers changing the Companion. For choosing and continuing work, start with the [Companion user guide](context-aware-delivery-companion-user-guide.md). The sections below describe the operating contract, ranking and implementation boundaries; they aren't additional setup steps for application teams.
+
+The Context-Aware Delivery Companion answers four practical questions from the
+current governed project state:
+
+1. What deserves attention now?
+2. Why does it deserve attention?
+3. Who can decide what happens next?
+4. Which installed personas are actively helping to examine this context?
+
+It is a read-only advisory layer over EWAI's existing execution contract. It does
+not create delivery permission, approve Build, complete Manual QA, accept risk,
+dispose of security findings, deploy or release software.
+
+> Companion and persona guidance is advisory. It cannot create delivery
+> permission, user evidence, specialist assurance or human acceptance.
+
+> Security validation is evidence, not certification or proof that this system is
+> secure. Tools can miss vulnerabilities and produce false positives. A qualified
+> human must review the scope, findings, limitations and residual risk before
+> release.
+
+## The shared contract
+
+Check-in, CLI, MCP, HTTP and the dashboard use the same
+`ewai.companion-guidance/v1` projection. The projection is bounded to eight
+recommendations, four actively engaged personas and 500 focus characters.
+
+It exposes only safe delivery identity, state, phase, progress, reason,
+accountable route, evidence classes, bounded blockers and an optional guarded
+handoff. It does not expose raw intent bodies, SPECS roots, credentials, security
+findings, disposition records, test output, model prompts or persona definitions.
+
+The four recommendation classes are:
+
+| Class | Meaning | Who or what moves it |
+| --- | --- | --- |
+| `human-decision` | Manual QA or another explicit human authority gate is next. | The named accountable reviewer or project owner. |
+| `continue` | The current governed harness can move forward. | The existing EWAI delivery harness after it rechecks permission. |
+| `start` | A prepared intent can enter governed delivery. | The existing EWAI delivery harness after it rechecks permission. |
+| `blocked` | No governed start or continue route is available. | The named delivery owner resolves the first evidenced blocker. |
+
+The class is derived from `execution.actions`, not from a board lane on its own.
+Human decisions outrank continuation, continuation outranks starts, and blocked
+work remains visible without being presented as executable.
+
+## Use the dashboard
+
+Open the project-local dashboard and choose **Companion**. The decision runway
+shows the current ranked recommendations. Select a card to replace the selected
+context, active personas and review questions with a fresh server-owned snapshot.
+
+The right-hand context panel shows:
+
+- the observed phase and progress;
+- why the item is ranked there;
+- the accountable route;
+- bounded blockers and evidence classes;
+- whether a guarded begin or continue handoff exists;
+- the personas actively engaged for this focus;
+- questions for the accountable person.
+
+At 960px the context panel moves below the runway. At 600px the card metadata and
+facts stack. Recommendation class and permission remain visible in text, so colour
+is never the only status signal.
+
+### Apply focus
+
+Focus is optional and can be an intent identity, decision or delivery concern. It
+is deliberately submitted, limited to 500 characters and returned in the safe
+contract. Applying or clearing focus replaces the active ensemble and questions;
+the dashboard does not accumulate perspectives from previous selections.
+
+Selecting a recommendation applies its safe identity as focus. This gives the
+server another opportunity to rank the item and select relevant personas rather
+than allowing the browser to pretend an old ensemble is still engaged.
+
+### Use a handoff
+
+A begin or continue button appears only when the current projection identifies the
+corresponding governed handoff. Clicking it opens the existing dashboard handoff
+dialog. Submission calls the established work-item handoff route, which rechecks
+the current execution action before recording the selection.
+
+The handoff does not begin code or change a phase. Return to the EWAI conversation
+and use the canonical delivery skill to claim and process it. Human-decision and
+blocked recommendations have no direct execution button.
+
+## Use CLI, MCP and HTTP
+
+Read the same projection from the CLI:
+
+```bash
+ewai companion status --project . --json
+ewai companion status --focus "Manual QA ownership" --project . --json
+```
+
+Agent integrations use the read-only MCP tool:
+
+```text
+ewai_companion_status
+```
+
+Its optional `focus` argument has the same 500-character limit. The tool exposes no
+companion write, approval, Build or release operation.
+
+The project-local loopback dashboard reads:
+
+```http
+GET /api/companion
+GET /api/companion?focus=Manual%20QA%20ownership
+```
+
+The server owns the project root. Unknown query parameters, oversized focus and
+unsafe control characters are rejected. POST is not supported.
+
+## Check-in spotlight
+
+`ewai checkin --json` retains the mandatory numbered Companion opening and adds a
+bounded `companion.spotlight`, `companion.activePersonas` and the invariant notices.
+Render the status first, then the returned heading and every `[id] label`. When a
+spotlight exists, identify it as advisory, name its accountable route and show the
+active persona names and tiers. End with the exact returned closing prompt.
+
+The spotlight is advisory context, not a replacement for the returned actions.
+**[6] Continue a piece of work** appears when work exists. **[7] Read about premium
+personas** and **[8] Set up premium personas** appear only when premium access
+isn't active. **[9] Configure the dashboard** remains available. Configuration also
+provides licence management when the setup prompts are hidden.
+
+## Persona behaviour
+
+The Standard host-model baseline plus installed project and core personas is a
+complete operating baseline. Relevant installed personal and premium personas can
+add specialist depth. Their installed tier, matched signals and engagement reason
+are visible whenever they are actively selected.
+
+Companion reads never install, update, synchronise or imitate premium content. If
+no premium library is installed, the response says so and continues normally. Use
+the separately consented premium sync process only when the user explicitly asks
+for it.
+
+Personas are lenses. They may frame questions, expose blind spots and improve the
+quality of a discussion. They are not stakeholder research, validation evidence,
+legal approval, security certification, user acceptance or accountable human
+judgement.
+
+## Implementation guide
+
+Integrations should depend on the public projection rather than reclassifying work
+items independently:
+
+1. Resolve the project through the existing EWAI locator.
+2. Load current work through the governed `listWorkItems` projection.
+3. Derive recommendation classes from permitted execution actions.
+4. Rank deterministically and apply bounded focus.
+5. Select active personas from installed project, core, personal and premium
+   metadata only.
+6. Return only the `ewai.companion-guidance/v1` allowlist.
+7. Delegate begin and continue to the existing guarded handoff route.
+8. Keep approval, Manual QA, security disposition, deployment and release outside
+   the Companion.
+
+Do not add browser model calls or model credentials. The host model interprets the
+bounded snapshot in conversation. The dashboard presents deterministic evidence,
+persona provenance and review questions without becoming a chat client.
+
+## Failure and recovery
+
+- **Empty:** show that no governed work is available; do not invent a next action.
+- **Projection failure:** show the contract error; do not infer a healthy state.
+- **Malformed or altered notices:** fail visibly because the authority boundary is
+  part of the public contract.
+- **Handoff rejected:** refresh guidance because the current execution permission
+  has changed.
+- **No persona match:** retain the complete Standard host-model baseline and state
+  that no specialist persona matched.
+- **No premium library:** continue without premium content; do not sync it.
+
+## Human acceptance checklist
+
+Before accepting an implementation, manually confirm:
+
+- ranking and class text match the current governed execution state;
+- selecting a card replaces context, personas and questions;
+- focus apply and clear work at desktop and 390px widths;
+- active persona names, tiers, signals and reasons are visible;
+- a handoff appears only for a currently permitted begin or continue route;
+- human-decision and blocked contexts cannot directly execute work;
+- both authority notices are always visible;
+- keyboard focus and screen-reader labels are meaningful;
+- no raw SPECS content, root, credential, finding or proprietary persona body is
+  exposed.
+
+Automated checks and this checklist prepare evidence. A named human still records
+Manual QA through the governed EWAI delivery gate.

package/Docs/context-aware-delivery-companion-user-guide.md

@@ -0,0 +1,184 @@
+# Context-Aware Delivery Companion user guide
+
+The Companion helps you understand what needs attention across an EWAI project,
+why it matters and who should act next. It gives you a ranked list of work so you
+can choose what to tackle without reading every delivery record.
+
+You do not need to use the command line or understand the technical delivery
+stages to use the Companion.
+
+> Companion and persona guidance is advisory. It cannot create delivery
+> permission, user evidence, specialist assurance or human acceptance.
+
+> Security validation is evidence, not certification or proof that this system is
+> secure. Tools can miss vulnerabilities and produce false positives. A qualified
+> human must review the scope, findings, limitations and residual risk before
+> release.
+
+## Open the Companion
+
+Open your project’s EWAI dashboard and select **Companion** from the navigation.
+Your EWAI check-in gives you the dashboard address when the project is ready.
+
+The screen has two main areas:
+
+- **Decision runway:** ranked cards showing the work that deserves attention.
+- **Selected context:** an explanation of the selected card, its evidence, who can
+  decide what happens next, the actively engaged personas and useful questions.
+
+The first card is the strongest current recommendation. Ranking is based on the
+project’s governed delivery state, not on an AI guess about what is urgent.
+
+## Understand the four recommendation types
+
+Every recommendation is labelled in words. Colour is supporting information only.
+
+### Human decision
+
+A named person must make or record a decision. This commonly appears when Build
+approval or Manual QA is next.
+
+Read who needs to decide and the questions in the context panel. The Companion
+does not approve the decision for you and does not provide a shortcut around the
+human gate.
+
+### Continue
+
+Work has already started and may be ready for its next step. EWAI still checks
+the required evidence and approvals before continuing.
+
+If a hand-off button is available, you can use it to select the work for your EWAI
+conversation. The delivery process checks permission again before anything moves.
+
+### Start
+
+An intent is prepared to enter the governed delivery process.
+
+A start hand-off selects it for your EWAI conversation. It does not start coding,
+approve Build or change the delivery phase by itself.
+
+### Blocked
+
+The work cannot currently start or continue. The card explains the first evidenced
+blockers and identifies the route for resolving them.
+
+Do not treat a fluent AI explanation as permission to proceed. Resolve the named
+blocker, refresh the Companion and confirm that the governed action has changed.
+
+## Select work and use focus
+
+Select a recommendation card to make it the active context. The Companion refreshes
+the explanation, questions and personas for that item.
+
+Use **Focus** when you want to examine a particular concern, for example:
+
+- “Who owns Manual QA?”
+- “What is blocking the supplier import?”
+- “Which work affects the product onboarding journey?”
+- “What needs a security review before release?”
+
+Apply one clear concern at a time. Clear the focus to return to the project-wide
+ranking.
+
+Changing focus replaces the previous context. If a person or persona is no longer
+relevant, it should disappear rather than remain as part of a permanent committee.
+
+## Understand actively engaged personas
+
+The context panel shows the actively engaged personas for the selected work. Each
+entry explains:
+
+- the persona’s name;
+- its tier, such as project, core, personal or premium;
+- the signals that made it relevant; and
+- why its perspective is being applied now.
+
+Personas help frame questions and expose blind spots. They are not real stakeholder
+evidence, approval or acceptance.
+
+The standard AI model and installed project/core personas provide the complete
+baseline. If relevant premium or personal personas are already installed, they can
+add specialist depth. Premium personas are optional: opening or focusing the
+Companion never downloads, installs or synchronises them.
+
+## Use a hand-off
+
+Selecting work prepares a request for your AI host; it doesn't itself implement the feature or complete a phase. Once the host accepts that handoff, continue the conversation there. You can inspect the saved work in the dashboard while the host performs the permitted task.
+
+A **Begin** or **Continue** hand-off appears only when the current project state
+permits that route.
+
+When you select it:
+
+1. EWAI checks the current permission again.
+2. The dashboard records which work you selected.
+3. You return to the EWAI conversation.
+4. The conversation identifies the hand-off and asks you to confirm proceeding.
+5. The guarded delivery process handles the next valid stage.
+
+If the project state changed after the card was displayed, the hand-off may be
+refused. Refresh the Companion and review the new blocker or accountable route.
+
+A hand-off does not approve Build, complete Manual QA, accept risk, dispose of a
+security finding, deploy software or release it.
+
+## Questions you still need to answer
+
+The Companion can organise evidence and suggest questions, but people remain
+responsible for decisions such as:
+
+- whether the intended outcome is correct;
+- whether the evidence is sufficient;
+- whether affected users or teams have been consulted;
+- whether a risk is acceptable and who owns it;
+- whether Manual QA has genuinely passed; and
+- whether the work is ready to deploy or release.
+
+When the evidence is incomplete, the correct result is an explicit question or
+blocker, not a confident recommendation.
+
+## Common situations
+
+### No recommendations are shown
+
+The project may have no governed work available, or the current projection may be
+unavailable. Refresh once. If the empty state remains, use the normal EWAI check-in
+to inspect or capture work. Do not infer that an empty screen means everything is
+complete.
+
+### The recommendation looks out of date
+
+Refresh the Companion. If the state still disagrees with the known project
+evidence, stop and ask the delivery owner to reconcile the durable intent,
+delivery state and project evidence.
+
+### The personas do not fit the selected concern
+
+Use a more specific focus and refresh. Personas are selected from what is actually
+installed. A missing specialist perspective should be shown as a gap rather than
+imitated.
+
+### A hand-off disappeared or was refused
+
+Permission changed between display and selection. Read the refreshed blockers and
+follow the accountable route. The refusal protects the governed process.
+
+### Premium personas are unavailable
+
+Continue normally. Premium content is optional and its absence does not make the
+Companion incomplete.
+
+## Before acting on a recommendation
+
+Check that you can answer yes to each relevant statement:
+
+- I understand why this item is ranked here.
+- I can distinguish observed evidence from advisory interpretation.
+- I know who owns the next decision or action.
+- The actively engaged personas fit this context.
+- Any blocker is explicit rather than hidden in a positive summary.
+- I am using only a currently advertised hand-off.
+- I am not treating Companion output as approval, assurance or release authority.
+
+For technical integration, configuration and acceptance details, use the
+[Context-Aware Delivery Companion operating and implementation guide](context-aware-delivery-companion-guide.md).

package/Docs/context-management-and-token-efficiency.md

@@ -0,0 +1,113 @@
+# Context management and token efficiency
+
+EWAI reduces repeated model input by assembling the minimum sufficient evidence for the work happening now. It does not shorten context by weakening engineering expectations. Standards, tests, security and privacy constraints, contradictions, task boundaries and human authority remain mandatory whenever the selected profile requires them.
+
+You normally don't prepare context manually: the relevant EWAI skill does that for its task. Use this guide when you want to understand why particular evidence or personas were selected, investigate missing context, or adjust a focused preparation. For example, ask EWAI: “Show me which evidence we're using for this intent and what's been left out.”
+
+Context preparation doesn't approve Build or Manual QA, accept risk, certify quality, deploy or release.
+
+## Inspect the evidence sent to the model
+
+Open **Configuration**, enable **AI context diagnostics** and save, then open that view in the sidebar. See [dashboard configuration](operations/dashboard-configuration.md) if you need help finding it.
+
+1. Choose a profile for the operation you want to inspect; the table below explains each one.
+2. Enter the intent slug.
+3. Enter a task ID for `build-task` or `fresh-context-review`.
+4. Add a narrow focus when it will improve relevance.
+5. Keep the default budget initially, or enter a deliberate bounded value.
+6. Optionally paste the exact previous digest to inspect segment and persona deltas.
+7. Select **Prepare manifest**.
+
+The view shows the context budget, which evidence was selected or left out, whether mandatory content fitted, the content digest and the active personas. It doesn't show the actual source bodies or model payload. On mandatory overflow it shows recovery choices and no downstream handoff. Preparing this manifest doesn't itself ask a model to do the work.
+
+## The seven profiles
+
+Budgets below are estimated input tokens, not words or a guarantee of a provider's billed usage. A token is a unit of text processed by a model; the exact token count depends on its tokenizer.
+
+| Profile | Use it for | Default token budget | Required evidence |
+| --- | --- | ---: | --- |
+| `companion` | deciding what deserves attention now | 2,000 | current delivery state and human route |
+| `intent` | shaping purpose and acceptance | 4,000 | canonical intent and authority boundary |
+| `plan` | designing implementation | 8,000 | accepted plan, claims and test obligations |
+| `build-task` | implementing one leased task | 12,000 | exact task, write set, allowed commands and stop conditions |
+| `fresh-context-review` | reviewing one task independently | 12,000 | tests first, exact diff scope, standards and verdict contract |
+| `phase-contribution-review` | reviewing an attributed phase thread | 6,000 | current phase state, attribution and human authority |
+| `design-system-apply` | applying resolved design guidance to one UI delivery | 6,000 | required contributions and design/human authority |
+
+The profiles are built-in policies for different operations. EWAI uses the appropriate profile in its workflow; when preparing directly, select one rather than combining several into a large generic prompt.
+
+## What gets selected
+
+Each candidate segment is classified as:
+
+- **mandatory:** must fit in full and retain all required markers;
+- **relevant:** included in priority order while budget remains;
+- **optional:** useful background that can be deferred.
+
+The assembler sorts deterministically, selects mandatory evidence first, and records one of `selected`, `reused`, `deferred`, or `overflow` for every segment. It hashes both content and policy, so a source or selection-policy change invalidates reuse. The fragment cache is private, project-local and disposable. Canonical SPECS and repository files remain the source of truth.
+
+If mandatory demand exceeds the budget, the result is `non-ready` with reason `mandatory-overflow`. No model payload is produced. Narrow the focus, raise the bounded budget, or split the operation. Do not remove a standard, test, security constraint or approval boundary to make the pack fit.
+
+## Persona swapping
+
+Every preparation considers installed project, personal, premium and core personas. EWAI selects a small ensemble from the profile and current focus, preferring the most relevant project and installed premium lenses where available. The **AI context diagnostics** view shows each active persona's:
+
+- name and tier;
+- matched signals;
+- engagement reason;
+- additions, retention and removals compared with an exact predecessor.
+
+When the work moves from product intent to implementation, performance, security or review, EWAI prepares context for that new operation. If you're using the CLI directly, prepare again with the new focus. Relevant personas replace those no longer needed. Personas remain advisory lenses, not participant evidence, specialist assurance, acceptance or approval. Missing premium content is optional enrichment; context preparation never downloads it.
+
+## Use the CLI
+
+Prepare context with:
+
+```bash
+ewai context prepare intent \
+  --slug governed-context-assembly \
+  --focus "outcomes and engineering performance" \
+  --project . \
+  --json
+```
+
+For a Build task:
+
+```bash
+ewai context prepare build-task \
+  --slug governed-context-assembly \
+  --task T-001 \
+  --focus "provider usage and latency" \
+  --project . \
+  --json
+```
+
+Trusted CLI and MCP hosts receive the transient `modelContext` and `deltaContext` needed for their immediate operation. Browser APIs return only safe manifests. None of these interfaces accepts an alternate root or unrestricted source path from an untrusted caller.
+
+## Understand usage numbers
+
+EWAI labels local estimates with `utf8-bytes-div-3-v1`. These figures are deterministic comparisons, not a claim about a specific provider tokenizer. Provider-reported usage, when a provider returns strict numeric input and output counts, is recorded separately from estimated usage. Missing provider usage stays unknown; it is never replaced with an estimate presented as actual consumption.
+
+An exact predecessor enables delta reporting and a smaller `deltaContext` for hosts that can safely reuse their immediately preceding context. The full context remains available to trusted hosts for correctness. A mismatched predecessor digest fails rather than guessing what the host remembers.
+
+## Run the packaged comparison
+
+If you want to inspect the bundled comparison, use:
+
+```bash
+ewai context benchmark --json
+```
+
+It uses a fixed comparison corpus, not your application's full workload. Read its per-profile results and failures; it doesn't measure provider latency, answer quality or actual account usage.
+
+If you're changing EWAI itself, follow [maintainer context benchmarks](maintainers/context-benchmarks.md) for the source-checkout scripts, thresholds and wider regression checks. Those aren't application setup requirements.
+
+## Recovery and privacy
+
+- Delete the context cache if it is suspect; the next run rebuilds it from canonical sources.
+- Treat `.ewai-pipeline/runtime/context-packs/` as private operational state, not durable project truth.
+- Share safe manifests when diagnostics are needed, not cached fragments or transient model payloads.
+- Use project-relative evidence references in manifests; absolute machine paths do not belong in safe projections.
+- If a digest, source, phase or task has changed, prepare a new pack and review the delta.
+
+Context efficiency is useful only when the resulting engineering work remains at least as reliable, testable, secure and accountable as the full-context baseline.

package/Docs/design-systems/design-system-implementation-guide.md

@@ -0,0 +1,85 @@
+# Design-system implementation guide
+
+This guide is for maintainers integrating the portable capability into EWAI projects and hosts. It adds no server backend, connector, or design-system management UI: the supported boundary is local CLI/domain functions, installed skills, project state, and delivery evidence.
+
+## Installed assets
+
+The npm package contains:
+
+- `config/design-system.schema.json` and the design-system extensions to the pack, project, and Organisation Blueprint schemas;
+- the bundled fallback under `packs/design-systems/default/`;
+- resolver, authoring, application, receipt, and prototype-manifest validation modules under `src/`;
+- `$ewai-design-system-author`, `$ewai-design-system-apply`, `$ewai-prototype-iteration`, and `$ewai-design-system-review`;
+- these operating guides.
+
+Run `ewai install --host auto` after an npm upgrade to copy the current skills to supported hosts. Project installations place Codex and Antigravity skills under `.agents/skills/`; Claude Code uses `.claude/skills/`.
+
+## Catalogue roots and authority
+
+EWAI discovers bundled, personal, and project-local packs. Source class is provenance, not precedence. Duplicate design-system IDs fail; dependencies and replacements are declared in the manifest. Project selection is independent and pinned in the project’s configured `SPECS/pipeline.yaml` with a matching strategy record.
+
+The bundled fallback works without configuration but is visibly unapproved. An Organisation Blueprint can recommend design-system IDs through its `design_systems` module, but recommendation never installs, selects, or copies them.
+
+## Application lifecycle
+
+1. Begin an EWAI delivery with UI Design in scope.
+2. Inspect the current design-system status and resolve stale pins.
+3. Run `ewai design-system apply DELIVERY_SLUG --focus TEXT --project PROJECT --json`.
+4. Handle `mandatory-overflow` without dropping required material.
+5. Give the transient `modelContext` only to the active model call. CLI output and persisted evidence intentionally omit it.
+6. Show active personas by safe reference, name, tier, matched signals, and reason. Do not persist definitions.
+7. Prepare and record persona review of the prototype plan.
+8. Produce the runnable prototype, capture separate evidence channels, and prepare a newly selected rendered-design persona ensemble.
+9. Record assessed findings within the one-to-three-cycle bound.
+10. Link the returned receipt, reviewed plan, and final cycle into the prototype manifest.
+11. Validate UI Design through the normal EWAI artefact and gate operations.
+
+The application service reuses `prepareContextPack`; do not create a second budgeting mechanism in host integrations. Non-UI context profiles receive no design-system segments.
+
+## Prototype manifest v3
+
+New delivery states are stamped with `artefactContracts.prototype: ewai.prototype-manifest/v3`. The manifest remains at:
+
+```text
+SPECS/6.Build/<delivery>/ui-design-assets/prototypes/manifest.json
+```
+
+Its selected HTML entry point stays inside `ui-design-assets/prototypes/`. v3 retains the v2 design-system linkage and adds:
+
+```json
+{
+  "schema": "ewai.prototype-manifest/v3",
+  "designSystem": {
+    "receiptPath": "ui-design-assets/design-system/receipt-<digest>.json",
+    "receiptDigest": "sha256:<receipt-digest>",
+    "effectiveDigest": "sha256:<effective-design-system-digest>"
+  },
+  "reviews": {
+    "plan": {
+      "path": "ui-design-assets/prototype-iterations/plans/plan-<digest>.json",
+      "digest": "sha256:<review-digest>"
+    },
+    "finalCycle": {
+      "path": "ui-design-assets/prototype-iterations/cycles/cycle-2-<digest>.json",
+      "digest": "sha256:<review-digest>",
+      "cycleNumber": 2
+    }
+  }
+}
+```
+
+The validator rejects missing, absolute, escaping, symbolic, invalid, altered, wrong-delivery, or digest-mismatched receipts and review records. It also requires the final cycle to reference the reviewed plan and selected HTML entry point. Historical v1 and v2 manifests without the new delivery stamp remain readable. To migrate a newly governed UI delivery, apply the active system, complete the persona-guided plan and rendered-design reviews, retain the selected prototype fields, change the schema to v3, and add all returned linkage.
+
+## Performance and privacy
+
+- Mandatory contributions fail non-ready when they exceed the explicit token budget.
+- Content-addressed cache entries are disposable and contain private context; receipts contain only safe projections.
+- Keep non-UI fixed fixtures byte-for-byte stable.
+- Maintain the local preparation contract of at most 75 ms median and 32 MiB aggregate peak RSS growth on the recorded test fixture.
+- Never send credentials, absolute paths, or premium persona bodies into receipts, summaries, logs, or manifests.
+
+## Recovery and testing
+
+Run focused tests for pack resolution, authoring, application, prototype linkage, review, installation, and packaging. Then run `npm run check`, `npm test`, and `npm pack --dry-run --json`. A dry run proves package contents only; it does not publish.
+
+When a receipt no longer matches, leave it immutable, reapply, and update the prototype manifest to the new receipt. When a selected pack is stale, require a new named selection approval. Manual QA, accessibility assurance, publication, deployment, and release remain separate.

package/Docs/design-systems/design-system-pack-authoring-guide.md

@@ -0,0 +1,95 @@
+# Design-system pack authoring guide
+
+Use a pack when guidance should be reused across features or projects. Keep a one-off delivery decision local; promote it only after evidence shows it is a repeatable rule.
+
+Ask EWAI: “Help me capture our product's design guidance as a reusable pack.” The `ewai-design-system-author` skill helps you examine the evidence and draft the guidance. You review the proposed rules, their sources and the files before approving installation. The examples below show the pack format and the optional direct commands.
+
+## Evidence-led authoring
+
+During the authoring conversation, check that each proposed rule has one of these evidence classes:
+
+- **owner-declared** — an accountable owner states the intended experience;
+- **observed** — product, repository, research, or rendered evidence supports it;
+- **inferred** — a useful hypothesis still awaiting confirmation;
+- **conflict** — sources or stakeholders disagree and the disagreement needs an owner decision.
+
+EWAI uses relevant core, project-local, personal and already installed premium personas as the subject changes. You see which perspectives are active and why; ask for a different perspective if an important concern is missing. Personas challenge evidence but don't approve guidance. Keep the resulting design rules in the pack, not the private body of a premium persona.
+
+## Pack structure
+
+For a complete starting point, use the [two-file design-system example](../examples/minimal-design-system.md). It includes the actual Markdown contribution as well as `pack.yaml`, then follows validation, installation and selection. The broader layout below shows where to put additional guidance as the pack grows; you don't need empty files for every possible contribution type.
+
+```text
+my-design-system/
+├── pack.yaml
+├── experience-promise.md
+├── principles.md
+└── components/
+    └── buttons.md
+```
+
+The manifest is data-only:
+
+```yaml
+schema: ewai.pack/v1
+id: org.example.product-design
+name: Example Product Design
+description: Reusable product experience guidance.
+version: 1.0.0
+type: design-system
+requires: []
+design_system:
+  compatibility:
+    ewai: 0.x
+  provenance:
+    kind: owner-declared
+    summary: Approved product principles captured with the product owner.
+  contributions:
+    - id: experience-promise
+      kind: experience
+      title: Experience promise
+      source: experience-promise.md
+      applicability: [ui-design, prototype, review]
+      required: true
+      replaces: []
+```
+
+Supported contribution kinds are `experience`, `principles`, `foundations`, `tokens`, `components`, `interaction`, `content`, `states`, `responsive`, `accessibility`, `motion`, `prohibited`, and `review`.
+
+Composition is explicit. Add dependencies under `requires`. When one contribution replaces another, identify the exact qualified target, for example:
+
+```yaml
+replaces:
+  - ewai.design-system.default:product-principles
+```
+
+Do not rely on bundled, personal, or project-local filesystem precedence.
+
+## Validate, review, then install
+
+Validation does not modify the candidate:
+
+```bash
+ewai design-system validate ./my-design-system --project . --json
+```
+
+Review the ID, version, compatibility, contribution metadata, provenance, and digest. After explicit confirmation, install that exact digest into one scope:
+
+```bash
+ewai design-system install ./my-design-system \
+  --scope project \
+  --expected-digest sha256:<candidate-digest> \
+  --yes \
+  --project . \
+  --json
+```
+
+Use `--scope personal` for a design system meant to be available across the current user’s projects. Installation stages beside the destination, revalidates the digest, atomically creates a new path, and refuses overwrite. It does not select or apply the pack.
+
+Symlinks, remote content, traversal, missing referenced files, incompatible EWAI majors, excessive content, duplicate identities, cycles, ambiguous contributions, and stale digests fail closed.
+
+## Version and governance
+
+Change the version whenever governed content changes. Treat a breaking meaning or contribution identity change as a major pack decision even while EWAI is pre-1.0. Preserve the evidence behind changes and obtain a new selection approval when a project pin becomes stale.
+
+An Organisation Blueprint can recommend the pack ID and version range for consistent setup. Keep the pack separate: Blueprint recommendations are metadata, not installation, selection, or copied design content.