@thebackstoryis/engineering-with-ai 0.2.9

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

@@ -0,0 +1,51 @@
+# Design-system review guide
+
+Use `$ewai-design-system-review` when a prototype or implemented surface exists. The review baseline is the immutable receipt linked by the selected artefact’s manifest, not whichever pack happens to be installed today.
+
+Ask EWAI: “Review this interface against the design guidance used to create it.” Point to the prototype or implemented surface and its manifest. EWAI helps compare the available evidence with that recorded guidance. You review the findings and decide which need correction or a separately approved exception; the review itself doesn't approve either.
+
+## Prepare the evidence
+
+Collect the selected artefact, `ui-design-assets/prototypes/manifest.json`, the linked receipt, and any separate evidence from:
+
+- source inspection;
+- rendered viewport checks at meaningful widths;
+- keyboard, pointer, touch, error, loading, empty, success, and recovery interaction;
+- assistive-technology checks;
+- representative-user research;
+- named Manual QA;
+- publication, deployment, or release authority.
+
+Do not merge these channels. A source check cannot prove rendered behaviour, and a persona cannot substitute for user research. Mark missing evidence absent.
+
+## Engage personas visibly
+
+EWAI brings in a small group of personas relevant to the finding: product, design, accessibility, content, domain or engineering. Core, project-local and personal personas support the standard path; already installed premium personas may add depth. The review shows their names, tiers, matched concerns and reasons, not their private definitions. You can challenge the selection or ask for a missing perspective.
+
+## Classify findings
+
+- `aligned` — cited artefact evidence satisfies a cited receipt contribution.
+- `approved-deviation` — a named accountable owner already approved this exact local difference in cited evidence.
+- `unresolved` — the artefact differs, evidence conflicts, an evidence channel is missing, or no owner approval exists.
+
+The review cannot itself make an `approved-deviation`. It should name the owner decision or correction required.
+
+A useful report records the contribution ID and digest, artefact location, observation, evidence channel, impact, active persona references, classification, and next action.
+
+## Example: a recovery message is missing
+
+Suppose the applied design guidance says a failed submission must retain entered data and offer a retry. In the rendered prototype, the error state clears the form.
+
+Record an `unresolved` finding against that contribution and the observed screen/capture. Ask the designer or engineer to preserve the input and show recovery, then inspect the revised result. A persona suggesting that correction isn't evidence the correction was made.
+
+If a product owner intentionally chooses a different behaviour, obtain and cite their actual deviation decision. Only then can the finding be `approved-deviation`; the reviewer can't grant that status by preference.
+
+## Route the outcome
+
+- Fix a defect in the current delivery when the artefact fails recorded guidance.
+- Retain an owner-approved deviation as delivery-local evidence.
+- Propose repeatable learning to a later `$ewai-design-system-author` cycle.
+
+Never edit an installed or upstream pack during review. Pack evolution has its own evidence, version, validation, installation, selection, and approval lifecycle.
+
+Static conformance and tests remain advisory evidence. A named human separately decides intentional deviation, Manual QA, specialist accessibility assurance, publication, deployment, and release.

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

@@ -0,0 +1,96 @@
+# Design-system user guide
+
+Use a design-system pack when new screens should follow the product's existing design decisions. The pack can describe components, layout, wording, accessibility and how empty or error states should behave. EWAI selects the relevant guidance for a delivery and records what it used, so the resulting prototype can be reviewed against it.
+
+There are three separate steps: **install** makes a pack available, **select** records the owner's choice for the project, and **apply** prepares its guidance for one delivery. The application receipt records that guidance; it isn't an approval of the design.
+
+Design systems sit alongside other EWAI tools, each with a different job:
+
+- a technology or stack pack describes how software is engineered;
+- an Organisation Blueprint describes organisation-owned defaults and can recommend design-system IDs;
+- a design-system pack describes the experience, interaction, content, visual foundation, component, state, accessibility, motion, prohibited-pattern, and review guidance relevant to a user interface;
+- personas supply temporary perspectives; they are not stored design rules or real-user evidence.
+
+## What happens by default
+
+Every project can resolve `ewai.design-system.default`, the bundled fallback. It gives standard LLM capabilities a useful, brand-neutral product-design baseline. You'll see it labelled **bundled fallback**: it isn't a design system approved for your project.
+
+Premium personas are optional. You can complete this workflow with the host and included personas, alongside relevant project-local or personal guidance. Already-installed premium personas can add specialist perspectives; this workflow doesn't download them.
+
+Ask EWAI which design system the project currently uses, or check the state directly:
+
+```bash
+ewai design-system status --project . --json
+ewai design-system list --project . --json
+ewai design-system inspect ewai.design-system.default --project . --json
+ewai design-system resolve ewai.design-system.default --project . --json
+```
+
+Status distinguishes `fallback`, an explicitly `selected` root, and a `stale` selection whose installed content no longer matches its approved digest.
+
+## Select a project design system
+
+Install the approved pack to make it available. Then resolve that pack and review the result before selecting it for this project. Selecting it records the owner's choice; applying it prepares guidance for a particular delivery.
+
+The commands below use `org.example.product-design` throughout. If it isn't installed, follow the [complete two-file example](../examples/minimal-design-system.md), or obtain the approved candidate folder from your pack owner:
+
+```bash
+ewai design-system validate ./example-design --project . --json
+ewai design-system install ./example-design --scope project --expected-digest <digest-from-validation> --yes --project . --json
+ewai design-system resolve org.example.product-design --project . --json
+```
+
+Use validation's `digest` for installation and resolution's `effectiveDigest` for selection. Don't interchange them. After reviewing the dependency graph and contributions, a named accountable owner can select that exact result:
+
+```bash
+ewai design-system select org.example.product-design \
+  --expected-digest sha256:<effective-digest> \
+  --approved-by "Named owner" \
+  --yes \
+  --project . \
+  --json
+```
+
+The selection writes a project pin and `SPECS/5.Strategy/design-system.md`. Filesystem order never grants override authority. Dependencies are explicit, and a contribution can replace another only with a qualified `pack-id:contribution-id` target.
+
+An Organisation Blueprint recommendation remains a recommendation. It never installs or selects the named design system, and it does not copy design content into the Blueprint.
+
+## Apply it to UI work
+
+Application belongs to an existing UI-bearing EWAI delivery:
+
+```bash
+ewai design-system apply customer-portal \
+  --focus "account overview, empty states and recovery" \
+  --project . \
+  --json
+```
+
+EWAI uses the existing bounded context assembler. Required contributions are mandatory; focus-matched material is relevant; other material can be deferred. The result shows selected and deferred contributions plus the active personas, including each safe reference, tier, matched signals, and engagement reason.
+
+If mandatory content exceeds the budget, the result is `mandatory-overflow`, no model payload or receipt is created, and the recovery is to narrow the focus, explicitly increase `--budget`, or split the operation. This protects design fidelity rather than quietly saving tokens by omitting mandatory guidance.
+
+A successful application returns immutable receipt and summary paths under:
+
+```text
+SPECS/6.Build/<delivery>/ui-design-assets/design-system/
+```
+
+The selected prototype records those digests in `ui-design-assets/prototypes/manifest.json` using `ewai.prototype-manifest/v3`. v3 also links the immutable reviewed plan and final persona-guided rendered-design cycle. The receipt proves what shaped the artefact; the reviews preserve critique and assessment. Neither proves that the result is attractive, usable, accessible, accepted, or ready to release.
+
+## Review and acceptance
+
+Ask EWAI to review the prototype plan, then review the rendered design once it exists. The `ewai-prototype-iteration` skill selects relevant available personas independently for those two reviews. You assess every finding rather than treating a persona's opinion as a decision.
+
+To check conformance, ask EWAI to compare the artefact with the design guidance recorded when it was created. The `ewai-design-system-review` skill labels each cited finding `aligned`, `approved-deviation` or `unresolved`. An approved deviation needs a separate named owner decision; neither review can create that approval.
+
+Source inspection, rendered viewport, interaction, assistive-technology, user research, Manual QA, and release are separate evidence channels. Any channel not performed remains explicitly absent. Named humans retain approval for intentional deviations, Manual QA, publication, deployment, and release.
+
+## Common recovery
+
+- `fallback`: continue for early design work or ask an accountable owner to select a reviewed root.
+- `stale`: re-resolve the installed packs and obtain a new named selection approval; never reuse the earlier digest.
+- duplicate ID or destination: version or rename the candidate; installation will not overwrite.
+- `mandatory-overflow`: narrow focus, increase the explicit budget, or split the surface.
+- receipt mismatch: reapply and link the new immutable receipt; do not edit the old receipt.
+- historical v1 or v2 manifest: it remains readable, but complete plan and rendered-design review linkage before finishing a newly stamped v3 UI Design phase.

package/Docs/design-systems/product-owner-guide.md

@@ -0,0 +1,49 @@
+# Product owner guide to EWAI design systems
+
+A design system helps you make the intended product experience repeatable. It is broader than visual tokens and components: it can capture the experience promise, product principles, interaction behaviour, content, meaningful states, responsiveness, accessibility, motion, prohibited patterns, and how work should be reviewed.
+
+## Decisions you own
+
+Start by asking EWAI to use your existing design guidance, or to help you capture it with `$ewai-design-system-author`. For example, show it the approved account page and explain that forms must use your existing components, errors must explain how to recover, and layouts must work on a phone. Review the proposed guidance before selecting it for the project. See the [user guide](design-system-user-guide.md) for selection and application.
+
+When that guidance is applied to a delivery, EWAI saves a **receipt**: a record of the exact guidance used. You can compare the prototype with that record later, even if the shared design system has changed.
+
+Product and design owners should decide:
+
+- whether the bundled fallback is sufficient for early work or a project design system should be selected;
+- which owner-declared principles are genuinely authoritative;
+- how conflicts between observed product behaviour, research, stakeholder expectations, and inferred guidance are resolved;
+- which guidance is mandatory and which can vary by surface;
+- whether a delivery-local difference is an intentional approved deviation;
+- whether repeated learning should be proposed for a future pack version;
+- whether the completed experience passes Manual QA and is ready for the next release decision.
+
+An Organisation Blueprint can recommend a design-system pack for a type of project. It does not make these decisions for you.
+
+A changed digest means the guidance differs from the version you reviewed. It doesn't mean “better” or “worse”. Ask to see the changed rules and affected screens before accepting a new version; don't approve an unexplained hash.
+
+## What you will see
+
+During authoring and application, EWAI shows the actively engaged personas and why each is relevant. Project-local personas can preserve knowledge specific to your organisation or product; personal personas can add an individual working lens; installed premium personas can deepen specialist critique. They are advisors, not stakeholders, and premium access is never required for the basic workflow.
+
+During application, you will see:
+
+- whether EWAI used your selected design system or its bundled fallback;
+- a digest identifying the exact resolved guidance;
+- which guidance was included or left for later, and why;
+- active personas and tiers;
+- whether mandatory guidance exceeded the context budget;
+- an immutable receipt for the prototype.
+
+During review, findings are `aligned`, `approved-deviation`, or `unresolved`. Only use `approved-deviation` when a named accountable owner has already recorded that decision.
+
+## Questions to ask
+
+- Does this experience promise describe the outcome we want users to feel and achieve?
+- Are important entry points, empty states, errors, recovery, and completion states covered?
+- Are we preserving existing authoritative components instead of recreating inconsistent alternatives?
+- Which user groups or contexts are absent from our evidence?
+- Did anyone actually inspect the rendered viewport, interactions, keyboard path, and assistive-technology behaviour?
+- Is a proposed exception truly local, or evidence that the design system should evolve?
+
+Application receipts and persona reviews improve traceability, but do not approve Build, visual quality, accessibility, Manual QA, publication, deployment, or release. Keep those human decisions explicit.

package/Docs/designing-organisation-blueprint-packs.md

@@ -0,0 +1,384 @@
+# Designing Organisation Blueprint Packs
+
+An Organisation Blueprint Pack is a reviewed, reusable starting point for projects that share an organisation's engineering standards and perspectives. It is a strict local `ewai.pack/v1` manifest plus bounded Markdown content.
+
+Use a blueprint to say, “projects of this kind begin with these defaults.” Do not use it to remove project-level Discovery or human approval.
+
+
+<!-- editorial: contents -->
+## On this page
+
+- [Start with the smallest useful pack](#start-with-the-smallest-useful-pack)
+- [What a pack can contain](#what-a-pack-can-contain)
+- [Design the pack before writing YAML](#design-the-pack-before-writing-yaml)
+- [Directory layout](#directory-layout)
+- [Complete V1 manifest](#complete-v1-manifest)
+- [Field rules](#field-rules)
+- [Write standard content](#write-standard-content)
+- [Write persona template content](#write-persona-template-content)
+- [Add optional organisation policy contributions](#add-optional-organisation-policy-contributions)
+- [Treat Starter Packs as governed receipts](#treat-starter-packs-as-governed-receipts)
+- [Add dependencies carefully](#add-dependencies-carefully)
+- [Install locally](#install-locally)
+- [Know the trust and size boundaries](#know-the-trust-and-size-boundaries)
+- [Understand digests](#understand-digests)
+- [Review and approve in Guided Setup](#review-and-approve-in-guided-setup)
+- [What approval creates](#what-approval-creates)
+- [Version and publish responsibly](#version-and-publish-responsibly)
+- [Troubleshooting](#troubleshooting)
+- [Author checklist](#author-checklist)
+- [Related guides](#related-guides)
+- [Contract sources](#contract-sources)
+
+## Start with the smallest useful pack
+
+Choose one reviewed standard, persona or policy that several projects genuinely need. Give it an owner, add it to one module, then validate the full Blueprint in a disposable project before adoption. The [policy-only example](policies/policy-pack-authoring-guide.md#add-it-to-a-blueprint) shows a complete small manifest and source file.
+
+Use [local installation](#install-locally) and [Guided Setup review](#review-and-approve-in-guided-setup) to try it. Dependencies, starters and optional modules are available when needed; they aren't fields you must populate with invented content.
+
+## What a pack can contain
+
+Each module contains zero or more of:
+
+- **Standards** — Markdown guidance materialised into project-owned SPECS after approval.
+- **Persona templates** — Markdown perspectives materialised as project personas after approval.
+- **Organisation policy contributions** — strict, declarative, data-only rules resolved into an optional project design-gate baseline after named approval.
+- **Governed Starter Packs** — provenance-bearing, target-aware receipts materialised only through an explicitly registered adapter, independent staged-tree verification, immutable preview, and named approval.
+
+A module is either required or optional. Required modules always apply. A participant can select declared optional modules on the root pack during Guided Setup.
+
+## Design the pack before writing YAML
+
+Start with four decisions:
+
+1. **Publisher identity.** Choose a stable lowercase slug, such as `northstar`. It becomes part of every pack ID and materialised persona ID.
+2. **Pack boundary.** Group defaults that should version and be reviewed together. Prefer a focused `engineering`, `data-platform`, or `regulated-delivery` pack over a catalogue of everything the organisation knows.
+3. **Module boundary.** Put unavoidable baseline requirements in required modules. Put genuinely situational concerns in optional modules.
+4. **Ownership.** Name the people accountable for each standard, persona template, dependency, and Governed Starter Pack outside the manifest in your normal review process.
+
+Do not make a rule required merely because it is popular. A required module becomes project truth when the blueprint is approved.
+
+## Directory layout
+
+Every discovered pack has a `pack.yaml`. Standard, persona, and policy `source` values are paths relative to that file.
+
+```text
+org-northstar-engineering/
+├── pack.yaml
+├── standards/
+│   ├── api.md
+│   └── release.md
+├── personas/
+│   └── api-governance-lead.md
+└── policies/
+    └── data-handling.yaml
+```
+
+Starter sources do not point to local pack content. They are source references accompanied by an independently verified version, aggregate logical-tree digest, licence, compatibility statement, and target roles.
+
+## Complete V1 manifest
+
+This example uses every supported item type and both module modes:
+
+```yaml
+schema: ewai.pack/v1
+id: org.northstar.engineering
+name: Northstar Engineering Baseline
+description: Reviewed engineering conventions for Northstar projects.
+version: 1.2.0
+type: organisation
+requires: []
+blueprint:
+  publisher:
+    id: northstar
+    name: Northstar Digital
+  compatibility:
+    ewai: 0.x
+  modules:
+    - id: api-conventions
+      name: API conventions
+      description: Authentication, endpoint, and error-handling rules.
+      required: true
+      standards:
+        - id: api-contract
+          title: API contract
+          source: standards/api.md
+      personas:
+        - id: api-governance-lead
+          name: API Governance Lead
+          source: personas/api-governance-lead.md
+      policies:
+        - id: data-handling
+          title: Data handling policy
+          source: policies/data-handling.yaml
+      starter_packs:
+        - id: api-service
+          name: Reviewed API service
+          source: https://example.invalid/api-service
+          version: 3.1.0
+          digest: sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+          licence: MIT
+          compatibility: Node 22
+          targets:
+            - role: application
+              source_path: application
+    - id: delivery-assurance
+      name: Delivery assurance
+      description: Release and handover evidence for higher-risk work.
+      required: false
+      standards:
+        - id: release
+          title: Release readiness
+          source: standards/release.md
+      personas: []
+      policies: []
+      starter_packs: []
+```
+
+The schema is strict: unknown fields fail validation rather than being ignored.
+
+## Field rules
+
+| Field | Rule |
+| --- | --- |
+| `schema` | Exactly `ewai.pack/v1`. |
+| `id` | `org.<publisher>.<pack>`. The publisher and pack segments use lowercase letters, numbers, hyphens, and supported dot-separated pack suffixes. |
+| `version` | Exact semantic version: `major.minor.patch`. |
+| `type` | Exactly `organisation`. |
+| `requires` | Organisation pack IDs only. Dependencies must be installed and compatible. |
+| `blueprint.publisher.id` | Lowercase slug and an exact match for the publisher segment in `id`. |
+| `blueprint.compatibility.ewai` | One major line such as `0.x`. It must match the installed EWAI major version. |
+| module `id` and item `id` | Lowercase slug; unique within their parent collection. |
+| module `required` | Boolean. Dependencies contribute only their required modules. |
+| standard/persona/policy `source` | Bounded relative path inside the pack; no absolute path, `..`, NUL byte, or symbolic link. |
+| Starter Pack `digest` | Canonical aggregate target-tree digest: `sha256:` followed by 64 lowercase hexadecimal characters. |
+| Starter Pack `targets` | One or more unique logical roles with non-overlapping bounded `source_path` values. |
+
+`description` on the pack is optional. All module `description` values are required. A persona item may omit `name`; materialisation then uses the source name or item ID.
+
+## Write standard content
+
+A standard source is ordinary Markdown. Write the rule, why it exists, where it applies, and what evidence demonstrates compliance.
+
+```markdown
+# API contract
+
+Use explicit compatibility rules for every externally consumed endpoint.
+
+## Evidence
+
+- Compatibility decision recorded in the intent.
+- Contract tests for every supported version.
+```
+
+On approval, EWAI adds provenance frontmatter and writes the content beneath:
+
+```text
+SPECS/4.Constraints/standards/organisation/<publisher>/<pack>/<module>/<standard>.md
+```
+
+## Write persona template content
+
+A blueprint persona source can provide descriptive frontmatter and a practical operating body:
+
+```markdown
+---
+name: API Governance Lead
+version: 1.0.0
+description: Applies the organisation's API compatibility and governance conventions.
+category: architecture
+tags:
+  - api
+  - governance
+capabilities:
+  - api-review
+---
+
+# API Governance Lead
+
+## Mission
+
+Protect compatibility and make the consequences of API decisions visible.
+
+## Questions to keep asking
+
+- Who consumes this contract today?
+- Which change is user-visible or irreversible?
+
+## Boundaries
+
+- This persona advises; accountable people approve project decisions.
+```
+
+During named approval, EWAI generates the final `ewai.persona/v1` metadata, forces the tier to `project`, adds source provenance, and writes the result beneath:
+
+```text
+SPECS/1.Scope/personas/project/<publisher>-<persona>.md
+```
+
+The resulting persona ID is `project.<publisher>.<persona>`.
+
+## Add optional organisation policy contributions
+
+Organisation Policy Design Gates are a separate Blueprint contribution from standards, personas, design systems, and Governed Starter Packs. A policy contribution is a strict `ewai.organisation-policy/v1` YAML document containing declarative rules, provenance, review roles, controls, exception posture, and an explicit unmatched outcome. It cannot contain scripts, prompts, hooks, endpoints, credentials, or other executable behaviour.
+
+Place a policy reference in the module whose applicability it shares:
+
+- a required module contributes its policies whenever that Blueprint is selected;
+- an optional root module contributes its policies only when a participant selects that module;
+- required dependency modules contribute their policies, while optional dependency modules remain unselected;
+- a Blueprint with no selected policy contributions leaves the project in the explicit, non-blocking `not-configured` state. EWAI does not invent a default policy.
+
+Guided Setup previews the resolved publisher, version, provenance labels, policy and rule counts, review roles, outcomes, pack pins, and exact effective digest without exposing policy bodies unnecessarily. A named person must approve that exact digest before EWAI writes the project-local policy baseline. A later upstream change can make the accepted baseline stale, but cannot rewrite it silently.
+
+Use the [Policy Pack Authoring Guide](policies/policy-pack-authoring-guide.md) for the strict policy shape and review checklist, and [Organisation Policy Design Gates](policies/organisation-policy-design-gates.md) for the project workflow and status meanings.
+
+> Organisation Policy Design Gates are design-time evidence only. They do not enforce production traffic, execute production code, certify compliance, approve Build or Manual QA, authorise release, or accept residual risk.
+
+## Treat Starter Packs as governed receipts
+
+A Starter Pack entry answers, “which reviewed starting point did we mean, and which logical parts does it contain?” Its fields must be sufficient for people and EWAI to verify the content independently.
+
+EWAI records the entry in the Organisation Blueprint receipt. A separately reviewed, explicitly registered source adapter may later place its content in bounded staging. EWAI does **not** supply credentials, execute retrieved starter content, trust adapter-reported inventories, deploy the result, or infer release approval.
+
+Keep technology-stack selection separate. A stack pack describes engineering guidance and tools; a Starter Pack identifies governed initial content; `starter_materialisation.targets` maps logical roles into this project's repository topology. See [Governed Starter-Project Materialisation](governed-starter-project-materialisation-guide.md).
+
+Repository analysis is separate again. An Organisation Blueprint Pack may declare `source_map.profiles` to classify organisation-specific files and select a registered safe analyser. Profiles do not contain executable hooks or retrieve content. They compose with core, technology, stack, and project profiles, and the active catalogue remains visible in Source Map coverage. Microsoft Power Platform and Salesforce format semantics belong in their technology packs; an organisation pack may narrow repository roles or classifications but should not duplicate or execute a provider parser. See [Repository Source Map](repository-source-map-guide.md) and [platform export analysis](platform-export-analysis-guide.md).
+
+The legacy `boilerplates` field remains readable as a one-role `application` Starter Pack receipt. Use `starter_packs` for new content and for every multi-target starter.
+
+## Add dependencies carefully
+
+Use `requires` when the pack cannot be understood or applied without another organisation pack.
+
+- Dependencies resolve in deterministic dependency-first order.
+- A missing, incompatible, or cyclic dependency blocks resolution.
+- Required modules from dependencies apply automatically.
+- Optional modules from dependencies are not selectable through the root pack.
+- Only optional modules declared by the selected root pack may be enabled.
+
+Keep dependency chains short. A pack should not hide a large and surprising policy inheritance tree.
+
+## Install locally
+
+You can distribute complete packs as local folders or through an organisation-operated [Team Hub resource registry](team-hub-resource-registry-guide.md). The registry supports inspecting and installing an exact version and digest; installation doesn't select or apply the Blueprint to a project.
+
+For folder-based distribution, place the complete pack directory beneath one of these local discovery roots:
+
+| Root | Intended ownership |
+| --- | --- |
+| EWAI package `packs/` | Bundled framework content maintained with EWAI. |
+| `~/.ewai/packs/` | Content installed for the current user. |
+| `<project>/.ewai-pipeline/packs/` | A project-local installed cache. |
+
+The project cache should be reproducible and disposable; maintain the authoritative pack in controlled version storage outside the cache.
+
+EWAI searches recursively for `pack.yaml` files, to a maximum depth of eight directories. If the same organisation pack ID appears in more than one root, catalogue loading fails instead of silently selecting one.
+
+## Know the trust and size boundaries
+
+The resolver refuses:
+
+- symbolic links and real paths that escape the pack root;
+- absolute or parent-traversing standard/persona/policy paths;
+- missing or non-file content sources;
+- manifests over 256 KiB;
+- individual referenced files over 1 MiB;
+- more than 5 MiB of referenced standard/persona/policy content per pack;
+- manifests nested beyond the configured depth;
+- invalid YAML, unknown fields, duplicates, incompatible versions, missing dependencies, and cycles.
+
+These checks constrain what EWAI reads. They do not certify that the organisation's written standard is correct.
+
+## Understand digests
+
+Each pack digest covers the raw `pack.yaml` bytes plus every referenced standard/persona/policy path and its raw bytes in sorted path order. Whitespace changes therefore change the digest.
+
+The resolved selection has a second digest covering the root pack, dependency versions and content digests, and applied modules. This lets Guided Setup detect a change between preview and approval.
+
+Never “tidy” an installed pack after it has been reviewed and assume it is the same input. Re-preview it and review the new digest.
+
+## Review and approve in Guided Setup
+
+1. Start or resume Guided Setup for the project.
+2. Choose one compatible installed Organisation Blueprint Pack.
+3. Select only the root pack's optional modules that apply.
+4. Review the resolved publisher, versions, digests, dependencies, applied modules, and counts of standards, personas, policy contributions, and Starter Pack receipts.
+5. Resolve every destination conflict. Preview is write-free; Governed Starter Pack materialisation has no force or merge path.
+6. Confirm that the active personas shown in the interface are the right lenses for this section. Blueprint persona templates do not become active project personas before approval.
+7. Give the accountable approver's name and approve the complete Discovery result.
+
+Immediately before writing, EWAI re-resolves the installed pack and compares the selection digest. Drift blocks approval. The transaction either writes the complete prepared result or rolls it back.
+
+## What approval creates
+
+Approval can create:
+
+- organisation standards beneath `SPECS/4.Constraints/standards/organisation/`;
+- project personas beneath `SPECS/1.Scope/personas/project/`;
+- an optional approved policy baseline at `SPECS/4.Constraints/organisation-policy/baseline.json` when selected contributions exist;
+- `SPECS/5.Strategy/organisation-blueprint.md`, containing the root, resolved packs, versions, digests, applied modules, approver, timestamp, and Starter Pack receipts;
+- a structured `blueprints.organisation` pin in the configured SPECS root's `pipeline.yaml`.
+
+The project-owned copies and receipt allow the approved baseline to remain intelligible even if the installed source later moves or changes.
+
+## Version and publish responsibly
+
+Use semantic versioning as an organisational promise:
+
+- **Patch** for clarification that does not change an obligation or persona stance.
+- **Minor** for additive optional guidance or a backward-compatible new module.
+- **Major** for changed required behaviour, removed content, incompatible identity, or a substantially changed decision lens.
+
+For every release:
+
+1. review the complete diff, including whitespace-sensitive digest changes;
+2. validate every dependency and referenced file;
+3. independently verify each Starter Pack version, canonical target digest, licence, compatibility statement, and logical target contract;
+4. record ownership and release approval in the pack's source repository;
+5. test the pack in a disposable project before distribution;
+6. communicate whether existing projects should remain pinned or deliberately adopt the new version.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Recovery |
+| --- | --- | --- |
+| Pack does not appear | Wrong root, filename is not `pack.yaml`, nesting is too deep, or `type` is not `organisation` | Confirm the local root, filename, depth, and manifest type. |
+| Manifest is invalid | Wrong field shape, unknown field, ID mismatch, duplicate ID, or malformed semantic version | Compare against the complete example and the strict field rules. |
+| Content source is rejected | Absolute path, `..`, symbolic link, missing file, escape, or size limit | Keep real regular files inside the pack and reduce content size. |
+| Duplicate pack ID | The same ID exists in two installed roots | Remove the stale installed copy; precedence is deliberately not guessed. |
+| Missing or cyclic dependency | A required ID is absent or the dependency graph loops | Install the exact dependency or redesign the dependency graph. |
+| Pack is incompatible | Its `ewai` major does not match the running package | Publish a compatible pack version or use the intended EWAI major. |
+| Approval reports drift | Pack bytes, referenced content, dependency, or selected module changed after preview | Reopen the preview and review the new digest and consequences. |
+| Starter preview reports conflicts | One or more destinations differ or are protected/unsafe | Review the existing project-owned truth outside materialisation, then prepare a new preview. EWAI never forces or merges. |
+
+## Author checklist
+
+- [ ] Stable publisher and pack IDs
+- [ ] Exact semantic version and compatible EWAI major
+- [ ] Focused modules with defensible required/optional choices
+- [ ] Unique IDs in every collection
+- [ ] Bounded standard and persona files inside the pack
+- [ ] Persona bodies describe mission, questions, evidence, and boundaries
+- [ ] Starter Pack targets, version, canonical digest, licence, and compatibility independently reviewed
+- [ ] Organisation-owned adapter validated and explicitly registered before use
+- [ ] Short, acyclic, installed dependency graph
+- [ ] Pack tested from a local discovery root
+- [ ] Preview consequences reviewed by the people affected
+- [ ] Named approval and project receipt retained
+
+## Related guides
+
+- [Working with personas](working-with-personas.md)
+- [Organisation Policy Design Gates](policies/organisation-policy-design-gates.md)
+- [Policy Pack Authoring Guide](policies/policy-pack-authoring-guide.md)
+- [Repository Source Map](repository-source-map-guide.md)
+- [Product Owner guide](product-owner-guide.md)
+- [All EWAI guides](README.md)
+
+## Contract sources
+
+- `src/organisation-blueprints.mjs` — strict manifest, roots, bounds, dependencies, digests, and safe projections
+- `src/discovery.mjs` — preview, materialisation, provenance, drift detection, approval, pinning, and rollback
+- `tests/organisation-blueprints.test.mjs` — valid examples and failure cases
+- `tests/discovery.test.mjs` — no-write preview and transactional application evidence