@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/persona-guided-prototype-iteration.md

@@ -0,0 +1,129 @@
+# Persona-guided prototype iteration
+
+EWAI reviews both the proposed prototype plan and the design that is actually produced. At each stage it identifies the most relevant available personas, shows why they are active, records their findings separately, and requires every finding to be assessed before the review can close.
+
+This is design evidence, not an autonomous approval system. Personas advise. A named person selects the prototype, Manual QA remains a human gate, and deployment and release remain separate decisions.
+
+Ask EWAI: “Review this prototype plan, then help me improve the rendered design using the relevant personas.” EWAI prepares the review inputs, shows the active perspectives and records their findings. You review the proposed responses, decide material trade-offs and select a design when it's ready. The optional CLI workflow below is for inspecting and recording the same evidence directly.
+
+For the complete path from intent and design-system application through screen planning, runnable HTML creation, browser evidence and production handoff, see the [screen prototype creation guide](screen-prototype-creation-guide.md).
+
+## The lifecycle
+
+1. EWAI applies the selected design system—or the clearly labelled bundled fallback—to the UI delivery.
+2. EWAI prepares a review of the prototype plan with relevant installed personas.
+3. You inspect their findings and the proposed responses; material deferrals and escalations need your decision.
+4. The host or designer revises the plan and creates the runnable prototype, with source and rendered evidence.
+5. EWAI selects relevant personas afresh for the actual rendered design and prepares the design review.
+6. You review the findings and responses. Accepted changes can lead to another recorded cycle within the configured limit.
+7. When concerns are resolved—or a trade-off needs your decision—you choose whether to select the prototype, request changes or pause.
+8. EWAI records the reviewed plan and final cycle links in `ewai.prototype-manifest/v3`. That evidence doesn't approve production Build or final Manual QA.
+
+Plan and design selection are separate on purpose. A Product Owner may be highly relevant to a journey plan, while an accessibility specialist or visual designer may become more relevant once responsive rendered evidence exists.
+
+## Actively engaged personas
+
+EWAI searches the available catalogue across:
+
+- core personas shipped with EWAI;
+- project personas under the configured `SPECS/1.Scope/personas/project` location;
+- personal personas installed for the current user;
+- premium personas already installed through the configured entitlement provider.
+
+The interface shows each active persona's safe ID, name, tier, category, matched signals and engagement reason. It also shows availability counts for every tier. Premium and personal personas add optional depth; the standard model with core and project personas remains a complete path. Prototype review never downloads or synchronises premium content.
+
+## CLI workflow
+
+The [complete plan and cycle inputs](examples/prototype-review-inputs.md) show all four files, the returned values to carry forward and the evidence required before design review. The host normally prepares these through `ewai-prototype-iteration`; review its findings and assessments rather than inventing hashes or persona IDs.
+
+Prepare a plan input JSON containing the intent digest, effective design-system digest, screens, journeys and selection signals, then run:
+
+```bash
+ewai prototype-review plan-prepare customer-portal \
+  --input plan-prepare.json \
+  --project . \
+  --json
+```
+
+Use the returned active ensemble to create evidence-cited findings. Keep each finding separate from its assessment, then record the complete result:
+
+```bash
+ewai prototype-review plan-record customer-portal \
+  --input plan-review.json \
+  --project . \
+  --json
+```
+
+After producing the runnable prototype, provide all seven evidence-channel states and prepare design review:
+
+```bash
+ewai prototype-review cycle-prepare customer-portal \
+  --input cycle-prepare.json \
+  --project . \
+  --json
+
+ewai prototype-review cycle-record customer-portal \
+  --input cycle-review.json \
+  --project . \
+  --json
+```
+
+Inspect or compare recorded evidence:
+
+```bash
+ewai prototype-review status customer-portal --project . --json
+ewai prototype-review compare customer-portal sha256:<earlier> sha256:<later> --project . --json
+```
+
+Comparison explains variance in causal order: inputs, personas, findings, assessments and output.
+
+## MCP and dashboard
+
+Agent hosts can use:
+
+- `ewai_prototype_review_status`;
+- `ewai_prototype_plan_prepare` and `ewai_prototype_plan_record`;
+- `ewai_prototype_cycle_prepare` and `ewai_prototype_cycle_record`;
+- `ewai_prototype_review_compare`.
+
+Enable **Contributions** in **Configuration** first; see [dashboard configuration](operations/dashboard-configuration.md). When the selected delivery is in UI Design, its contextual prototype review panel shows persona availability, Actively engaged personas, matched signals, engagement reasons, findings, dispositions and the derived next action. The panel accepts the same bounded JSON contracts and does not expose persona bodies or accept a project-root override.
+
+## Findings and dispositions
+
+Each persona finding has a stable identity based on persona, concern code and evidence references. Changing explanatory wording does not silently turn the same concern into a new issue.
+
+Every finding receives exactly one disposition:
+
+- `incorporate`;
+- `incorporate-with-modification`;
+- `defer`;
+- `reject`;
+- `escalate`.
+
+Each disposition requires rationale. Modified incorporation also records the modification. Material deferral and escalation require a human decision.
+
+## Evidence channels
+
+Design cycles report `source`, `rendered-viewport`, `interaction`, `assistive-technology`, `user-research`, `manual-qa`, and `release` separately. Source and rendered-viewport evidence are required before persona design review. Missing channels remain explicitly missing. Persona feedback is never presented as user research, Manual QA, accessibility certification or release evidence.
+
+## Iteration bounds and next action
+
+The default design limit is two cycles and the supported range is one to three. EWAI derives one of:
+
+- `iterate` when assessed feedback should be incorporated and capacity remains;
+- `ready-for-human-selection` when no assessed concern requires another cycle;
+- `human-decision-required` when material uncertainty is escalated, deferred, or remains at the cycle limit.
+
+The limit prevents an unbounded model-to-model design loop. It never converts unresolved feedback into acceptance.
+
+## Prototype manifest v3
+
+New UI deliveries use `ewai.prototype-manifest/v3`. It retains selected-prototype and design-system receipt fields from v2 and adds digest-checked links to the immutable reviewed plan and final design cycle under:
+
+```text
+SPECS/6.Build/<delivery>/ui-design-assets/prototype-iterations/
+├── plans/
+└── cycles/
+```
+
+Historical v1 and v2 manifests remain readable. A v3 delivery must link review evidence that belongs to the same delivery, matches the recorded digest, ties the final cycle to the reviewed plan, and references the selected HTML entry point.

package/Docs/personas/organisation-specific-personas.md

@@ -0,0 +1,103 @@
+# Creating organisation-specific personas
+
+Use this guide to encode a reusable organisational perspective without turning a persona into an unreviewed policy engine.
+
+## Decide whether this should be a persona
+
+Use a persona for context-sensitive judgement, questions, and trade-offs. Use a standard for a mandatory obligation.
+
+| Need | Best home |
+| --- | --- |
+| “All public APIs must use the approved authentication pattern.” | Organisation or project standard |
+| “Ask how this design uses our authentication, versioning, and error conventions.” | Organisation API persona |
+| “This project uses a temporary exception until migration completes.” | Project constraint or decision |
+| “Challenge whether the exception creates consumer or operational risk.” | Project persona |
+
+Often the best design is a standard plus a persona that tests how the standard applies in context.
+
+## Choose the distribution scope
+
+- **Project persona:** use when knowledge is specific to one product, client, team, or evidence set.
+- **Blueprint persona template:** use when a reviewed perspective should be proposed consistently to several projects and become project-owned after approval.
+- **Personal persona:** use for an individual's reusable working lens, not organisational authority.
+- **Premium persona:** use the managed entitled library; do not copy it into an organisation pack.
+
+## Gather source material
+
+Work with the accountable organisational experts and collect:
+
+- approved standards and decision records;
+- recurring design and review questions;
+- examples of accepted and rejected approaches;
+- operating constraints and failure experience;
+- escalation and exception routes;
+- vocabulary used across teams;
+- known boundaries where another specialist must decide.
+
+Do not encode one person's informal preference as organisation policy.
+
+## Model the perspective
+
+An organisation API designer, for example, might:
+
+- protect consumer compatibility and predictable change;
+- ask how authentication, error envelopes, pagination, and idempotency follow organisation standards;
+- request evidence from contract tests and consumer journeys;
+- identify where a deliberate exception needs governance review;
+- avoid selecting technologies outside the approved decision process;
+- remain advisory.
+
+Use the [persona authoring cookbook](persona-authoring-cookbook.md) for metadata and body structure.
+
+## Package through a Blueprint
+
+A Blueprint persona template should use the complete project-persona Markdown shape. The Blueprint manifest references it through a bounded relative path. During Guided Setup:
+
+1. the template is previewed with its source pack and module;
+2. the Product Owner reviews its consequences;
+3. named approval materialises it under the configured project-persona directory;
+4. provenance records pack ID, version, digest, approver, and time;
+5. the materialised persona participates with `tier: project`.
+
+The organisation supplies a reviewed starting point. The approving project owns the resulting persona.
+
+## Design for contextual engagement
+
+Choose metadata that matches the decisions where the lens is useful:
+
+- architecture personas should use architecture, integration, API, data, resilience, or security signals as appropriate;
+- operational personas should use deployment, observability, incidents, support, recovery, or continuity;
+- governance personas should use controls, audit, risk, compliance, privacy, or assurance;
+- product personas should use outcomes, journeys, accessibility, adoption, research, or value.
+
+Do not add all organisation vocabulary to every persona. The resolver should be able to swap specialists in and out as the subject changes.
+
+## Review and pilot
+
+Before publishing:
+
+1. validate the persona Markdown and Blueprint manifest;
+2. run relevant and irrelevant Discovery sections;
+3. inspect name, tier, matched concerns, and engagement reason;
+4. compare questions with real subject-matter experts;
+5. confirm mandatory rules remain in standards;
+6. pilot with more than one project;
+7. remove confidential examples and project-specific facts;
+8. assign maintenance and deprecation ownership.
+
+## Example review questions
+
+- Does this persona express one coherent organisational perspective?
+- Which approved sources support it?
+- Would a project know when its advice is optional or mandatory?
+- Are exceptions routed to a named human process?
+- Does it duplicate a core or premium persona without adding local value?
+- Does it match only relevant Discovery contexts?
+- Can the project safely own and improve the materialised version?
+
+## Related guides
+
+- [Designing Organisation Blueprint Packs](../designing-organisation-blueprint-packs.md)
+- [Persona governance](persona-governance.md)
+- [Internal Blueprint catalogue](../blueprints/internal-blueprint-catalogue.md)
+- [Project standards authoring](../standards/project-standards-authoring.md)

package/Docs/personas/persona-authoring-cookbook.md

@@ -0,0 +1,176 @@
+# Persona authoring cookbook
+
+Use this guide to write a persona that improves questions and decisions without impersonating a stakeholder or becoming hidden policy.
+
+Read [Working with personas](../working-with-personas.md) first for source tiers, paths, commands, premium sync, and contextual selection.
+
+## Start with one distinct job
+
+A useful persona examines a distinct set of problems and explains their consequences for a recognisable role or outcome.
+
+Good missions:
+
+- help a service operator assess observability and safe recovery;
+- test a finance workflow for reconciliation and audit evidence;
+- challenge an API design against the organisation's authentication and compatibility approach;
+- examine a journey from an assistive-technology user's perspective, grounded in real research.
+
+Weak missions:
+
+- “make everything better”;
+- “be an expert in all fields”;
+- “approve secure code”;
+- “represent all users”.
+
+If two perspectives have different evidence, concerns, or authority boundaries, create two focused personas.
+
+## Choose the correct scope
+
+```bash
+# Reusable lens owned by one practitioner
+ewai persona create service-designer \
+  --name "Service Designer" \
+  --category product
+
+# Perspective owned and versioned by one project
+ewai persona create payments-operator \
+  --scope project \
+  --project . \
+  --name "Payments Operator" \
+  --category operations
+```
+
+Do not recreate managed premium content. Add a project persona only when the project has a genuine local perspective or evidence-backed refinement.
+
+The create command produces a Markdown starting file, not a finished expert. Open the returned path and write the mission, decision methods, questions and boundaries using the structure below. Keep existing frameworks, decision trees and attribution when refining an established persona.
+
+Then follow [Test the persona](#test-the-persona): check it appears, use it against a real but safe decision, and review whether its advice is specific and useful. Listing successfully proves discoverability, not the quality of its judgement.
+
+## Make the persona easy to find
+
+```markdown
+---
+schema: ewai.persona/v1
+id: project.payments-operator
+name: Payments Operator
+version: 0.1.0
+description: Examines payment changes for reconciliation, exception handling, observability, and recoverable operations.
+category: operations
+pack: ewai.personas.project
+tier: project
+tags:
+  - payments
+  - reconciliation
+  - incidents
+capabilities:
+  - operational-readiness
+  - exception-design
+  - recovery-review
+---
+```
+
+Metadata drives discovery and selection:
+
+- **ID:** stable machine identity; do not encode a person's name.
+- **Name:** short human label shown in the interface.
+- **Version:** change deliberately when the perspective changes.
+- **Description:** the decisions, outcomes, and risks this persona examines.
+- **Category:** one useful domain grouping.
+- **Tags:** plain-language concepts likely to match Discovery sections or answers.
+- **Capabilities:** concrete review or reasoning activities.
+
+Avoid keyword stuffing. Relevance comes before tier, and a persona that matches everything makes the ensemble less meaningful.
+
+## Use a dependable body structure
+
+The sections below are a starting point, not a limit. Keep any useful decision trees, named methods, worked examples, checks and response templates the role needs. Match the depth and response format to the request; don't force a full report when a short answer is enough.
+
+### Mission
+
+State the outcome the perspective is trying to protect. Keep it to one or two paragraphs.
+
+### Operating stance
+
+Explain how the persona reasons and what evidence it prefers. For example:
+
+- trace payment totals to an accountable ledger;
+- distinguish transient processing from durable settlement;
+- prefer observable, repeatable recovery over manual heroics.
+
+### Questions to keep asking
+
+Write questions that change the quality of the work:
+
+- How will an operator detect a partial failure?
+- Can reconciliation distinguish duplicate, delayed, and missing events?
+- Who may retry this action, and is it idempotent?
+- What evidence proves recovery completed safely?
+
+Avoid generic questions such as “Is this good?” or instructions to always choose one technology.
+
+### Boundaries
+
+Every persona should say:
+
+- it advises rather than approves;
+- real stakeholder evidence takes priority;
+- assumptions and missing evidence must be explicit;
+- mandatory policy remains in project standards, not persona opinion.
+
+Add any domain-specific boundary, such as requiring a real privacy or legal reviewer for regulated interpretation.
+
+## Ground project personas in evidence
+
+When a project persona represents users or organisational roles, link its development to interviews, observation, approved process documentation, or accountable subject-matter review. Do not embed confidential transcripts in the persona.
+
+Separate:
+
+- **observed needs and constraints** supported by evidence;
+- **working hypotheses** awaiting validation;
+- **design prompts** used to challenge the team;
+- **authority** retained by real people.
+
+## Test the persona
+
+1. Confirm it parses and appears:
+
+   ```bash
+   ewai persona list --project . --query payments
+   ```
+
+2. Run representative Discovery sections.
+3. Confirm its name, tier, matched concerns, and engagement reason make sense.
+4. Check that it is absent from unrelated sections.
+5. Compare its questions with the real stakeholder's view.
+6. Narrow metadata or split the persona if it dominates too many contexts.
+
+Guided Discovery selects up to four relevant personas and deliberately tries to include a matching project and premium lens. Test the ensemble, not only the persona in isolation.
+
+## Common authoring mistakes
+
+| Mistake | Better approach |
+| --- | --- |
+| Persona contains mandatory rules | Put enforceable obligations in project standards; let the persona ask how they apply. |
+| Persona pretends to be a named colleague | Describe a role or evidence-backed user group without imitating an individual. |
+| Every tag is included | Use a small discriminating vocabulary. |
+| Technology choice is hard-coded without context | State the organisation's decision criteria and link to the governing standard. |
+| Persona gives approval | Preserve named human approval outside the persona. |
+| Premium persona is copied and edited | Create a separately owned project persona and explain the local difference. |
+| Persona never retires | Give it an owner, review trigger, and version history. |
+
+## Author checklist
+
+- [ ] One distinct outcome and perspective.
+- [ ] Correct personal or project ownership.
+- [ ] Stable valid metadata.
+- [ ] Specific, restrained tags and capabilities.
+- [ ] Evidence expectations and useful questions.
+- [ ] Clear advisory and stakeholder boundaries.
+- [ ] Tested in relevant and irrelevant Discovery contexts.
+- [ ] Reviewed by the real role or subject-matter owner where possible.
+
+## Related guides
+
+- [Persona governance](persona-governance.md)
+- [Organisation-specific personas](organisation-specific-personas.md)
+- [Persona engagement UI](persona-engagement-ui.md)

package/Docs/personas/persona-engagement-ui.md

@@ -0,0 +1,133 @@
+# Persona engagement UI guide
+
+This is an implementation and design guide for teams presenting EWAI's active personas in Guided Discovery, Blast Radius or another conversational surface. The response fields below describe the current contract. The later presentation and interaction sections are design recommendations, not a claim that every EWAI screen already provides those controls. For everyday use, see [Working with personas](../working-with-personas.md).
+
+## The user question the UI must answer
+
+At any moment, a participant should be able to answer:
+
+> Which perspectives are influencing this conversation, where did they come from, and why are they relevant now?
+
+Visibility is not decoration. It helps participants challenge missing, irrelevant, or overrepresented perspectives.
+
+## Current response contract
+
+Guided Discovery returns active personas with:
+
+- `id`;
+- `name`;
+- `tier`;
+- `category`;
+- a bounded description;
+- `matchedSignals`;
+- `engagementReason`.
+
+The response also states that guidance is advisory and human evidence takes priority. The ensemble can change by section, answer context, or proposed-change evidence, with up to four relevant personas selected.
+
+Persona-driven test preparation uses the same safe ensemble contract. Its dashboard [coverage loom](../quality/persona-driven-test-scenarios.md) keeps source, persona concern, and proof route visibly separate.
+
+## Minimum visible treatment
+
+For each active persona, display:
+
+1. **Name** as the primary label.
+2. **Tier/source** as provenance, not status or authority.
+3. **Engagement reason** in plain language.
+4. **Matched concerns** when the user wants more detail.
+
+Also provide an explicit empty state when no persona matches. Do not silently fall back to implying that an unnamed generic expert is active.
+
+## Show change over time
+
+When the section or evidence changes:
+
+- identify personas that joined;
+- identify personas that left;
+- explain the new concern that caused the change;
+- retain access to the current ensemble without interrupting the main task.
+
+Recommended practice is a compact persistent summary with an expandable detail panel. Avoid a constantly animating “agent conversation” that distracts from the human discussion.
+
+## Language to use
+
+Prefer:
+
+- “Active perspectives”;
+- “Engaged because…”;
+- “Matched concerns”;
+- “Advisory”;
+- “Project”, “premium”, “personal”, or “core” source.
+
+Avoid:
+
+- “Decision-makers”;
+- “Approvers”;
+- “The user says…” when no real user spoke;
+- “Verified expert” unless a separate assurance process defines that claim;
+- authority implied by a paid or higher-precedence tier.
+
+## Interaction states
+
+| State | UI response |
+| --- | --- |
+| Loading | Preserve the prior confirmed ensemble and say a new selection is being evaluated. |
+| Active | Show name, tier, reason, and optional matched concerns. |
+| No match | Explain that no installed persona matched; invite review of missing perspectives. |
+| Parse problem | Exclude the unsafe definition and link to persona troubleshooting. |
+| Premium unavailable | State that the managed library is not installed or accessible; do not prompt an automatic download. |
+| Changed draft revision | Preserve entered work and ask the user to reconcile the newer revision. |
+
+## Allow challenge without pretending to configure authority
+
+Useful actions include:
+
+- “Why is this persona active?”
+- “What evidence is this question based on?”
+- “This perspective is not relevant.”
+- “A stakeholder perspective is missing.”
+- “Open persona details.”
+
+If the current product does not support manual pinning or exclusion, present these as feedback or follow-up actions rather than controls that appear to have changed the resolver.
+
+## Accessibility
+
+- Do not encode tiers or active/inactive state by colour alone.
+- Make change announcements available to assistive technology without repeatedly stealing focus.
+- Keep reasons concise and expandable.
+- Support keyboard inspection of every persona.
+- Use readable source labels rather than unexplained icons.
+- Preserve the active ensemble when zoomed or reflowed.
+
+## Privacy and content boundaries
+
+Do not expose proprietary persona bodies merely to explain selection. Public metadata, matched concerns, and the generated reason are sufficient for the active summary.
+
+Do not display filesystem paths to ordinary participants. Maintainer diagnostics may expose a local path in a separate technical view with appropriate access.
+
+## Acceptance checklist
+
+- [ ] Active personas remain visible throughout each section.
+- [ ] Name, tier, reason, and matched concerns are available.
+- [ ] Tier is presented as provenance, not authority.
+- [ ] Join/leave changes are understandable.
+- [ ] No-match and unavailable-premium states are honest.
+- [ ] Advisory and human-evidence boundaries are visible.
+- [ ] The UI does not expose managed persona content.
+- [ ] Keyboard, screen-reader, zoom, and colour-independent use were checked.
+
+## Related guides
+
+- [Working with personas](../working-with-personas.md)
+- [Guided Discovery facilitator guide](../guided-discovery-facilitator-guide.md)
+- [Blast Radius and Impact Routing](../blast-radius-and-impact-routing-guide.md)
+- [Persona-driven test scenarios](../quality/persona-driven-test-scenarios.md)
+- [Persona authoring cookbook](persona-authoring-cookbook.md)
+
+## Current contract sources
+
+- `src/runtime/guided-discovery.mjs`
+- `src/runtime/impact-analysis.mjs`
+- `src/runtime/persona-engagement.mjs`
+- `src/runtime/dashboard-server.mjs`
+- `tests/guided-discovery.test.mjs`
+- `tests/impact-analysis.test.mjs`

package/Docs/personas/persona-governance.md

@@ -0,0 +1,118 @@
+# Persona governance guide
+
+Use this guide to keep persona libraries useful, attributable, current, and appropriately bounded over time.
+
+## Govern source and authority separately
+
+| Persona source | Content owner | Change route | Decision authority |
+| --- | --- | --- | --- |
+| Core | EWAI maintainers | Framework release | None; advisory only |
+| Premium | Managed pack publisher | Explicit entitled sync | None; advisory only |
+| Personal | Individual practitioner | Personal library change | None; advisory only |
+| Project | Project team | Reviewed project SPECS change | None; advisory only |
+| Blueprint-derived project | Project after approval | Project change process | None; advisory only |
+
+Higher selection precedence does not grant greater authority. In Guided Discovery, relevance is scored first; project, premium, personal, and core form the tier tie-break order.
+
+## Assign an owner and review trigger
+
+Every project or organisation persona should have:
+
+- a content owner;
+- the real roles or evidence it is grounded in;
+- a current version;
+- a last-reviewed date in adjacent project governance records;
+- events that trigger review;
+- a retirement or replacement route.
+
+The current persona schema does not define all governance metadata. Keep additional review records in project SPECS or the organisation catalogue rather than adding unsupported frontmatter.
+
+## Review when context changes
+
+Review a persona when:
+
+- user research contradicts or deepens its assumptions;
+- the represented role's responsibilities change;
+- regulation, policy, or operating practice changes;
+- its questions repeatedly produce low-value or duplicated advice;
+- it appears in irrelevant Discovery sections;
+- it fails to appear when its perspective is needed;
+- a Blueprint or premium release changes adjacent perspectives;
+- the named owner leaves or changes role.
+
+## Make changes traceable
+
+For a material change:
+
+1. explain the evidence or decision that prompted it;
+2. update mission, stance, questions, metadata, and boundaries coherently;
+3. increase the persona version;
+4. inspect catalogue discovery with `ewai persona list`;
+5. test relevant ensemble selection and UI reasons;
+6. have the project or subject-matter owner review it;
+7. record replacement or migration effects.
+
+Do not change only the description to force a ranking result while leaving the underlying perspective inconsistent.
+
+## Resolve duplicate and conflicting personas
+
+Two personas may legitimately disagree. First determine whether they represent:
+
+- different stakeholder outcomes;
+- different organisational policies;
+- the same role at different scopes;
+- an obsolete and a current version;
+- accidental duplication.
+
+Keep distinct perspectives when the tension is useful and name the decision owner. Merge only when ownership and evidence are truly the same. Retire obsolete duplicates rather than relying on tier ordering to hide them.
+
+## Manage premium updates
+
+Premium personas are an explicitly synced managed library. Check-in reports entitlement, installation, and update status without downloading content.
+
+When an update is offered:
+
+1. confirm the environment is entitled and permitted to receive it;
+2. preserve any project decision that depends on the current perspective;
+3. run the explicit sync only with consent;
+4. inspect changed catalogue metadata and relevant ensemble behaviour;
+5. do not modify or publish the managed cache;
+6. create a project persona if a durable local perspective is needed.
+
+```bash
+ewai persona premium sync --project . --yes
+```
+
+An update checks licence access and downloads a verified release ZIP from the website. It doesn't pull a Git branch. If the managed files were edited, belong to another seat or fail validation, stop and inspect the error; don't force replacement. See [setup and recovery](../operations/premium-personas-setup.md).
+
+Status checks can enforce a confirmed expiry of the matching team licence. They preserve personal and project personas; individual subscriptions retain the installed pack after expiry but no longer receive updates.
+
+## Retire a persona safely
+
+The public CLI does not provide a persona-retire command. Retirement is therefore a reviewed ownership action:
+
+- identify replacement or explain why the lens is no longer needed;
+- check intents, Blueprints, or guides that refer to the persona ID;
+- retain history needed to interpret past decisions;
+- remove or archive the source through normal version control;
+- refresh the catalogue and confirm it is no longer selected;
+- communicate the change to affected teams.
+
+Never delete a managed premium persona independently of its managed library.
+
+## Audit questions
+
+- Can we identify the owner and evidence behind each project persona?
+- Are personas written as perspectives rather than hidden policies?
+- Do active-persona reasons remain understandable?
+- Are stale keywords causing irrelevant selection?
+- Are critical real stakeholder perspectives missing?
+- Have managed personas been copied into public or project history?
+- Can past project decisions still be interpreted after a persona changes?
+
+## Related guides
+
+- [Working with personas](../working-with-personas.md)
+- [Persona authoring cookbook](persona-authoring-cookbook.md)
+- [Organisation rollout](../organisation-rollout-guide.md)
+- [Governance team guide](../governance/governance-team-guide.md)