agentera 3.0.0-dev.5 → 3.0.0-next.1

package/bundle/references/meta/documentation-inventory.md

@@ -4,7 +4,14 @@ Maintainer inventory of repository documentation, workpapers, and legacy surface
 Authoritative Agentera docs live under `references/`, `skills/agentera/`, and root
 guides — not under `docs/`.
 
-**Last reviewed:** 2026-05-23
+**Last reviewed:** 2026-06-05
+
+## Design docs under `docs/`
+
+| Path | Topic |
+| ---- | ----- |
+| `docs/packaging/v3-packaging.md` | v3 CLI npm/Bun distribution contract |
+| `docs/consolidation/monorepo-plan.md` | Product pivot, `@agentera/*` package layout, migration checklist (D67) |
 
 ## Authority stack
 
@@ -17,7 +24,7 @@ guides — not under `docs/`.
 | Benchmark contract | `references/analysis/startup-measurement-contract.yaml` |
 | Benchmark runbook | `references/analysis/benchmark.md` |
 | JSON surface budgets | `scripts/json_output_surface_manifest.yaml` |
-| Project drafts | `docs/` (gitignored except `docs/README.md`) |
+| Project drafts | `docs/` (gitignored except `docs/README.md`, `docs/packaging/`, `docs/consolidation/`) |
 
 ## `docs/` policy
 
@@ -40,4 +47,3 @@ Live JSON enforcement uses `scripts/json_output_surface_manifest.yaml` only.
 
 - Replace live `SPEC.md` references in `UPGRADE.md`, hooks, adapter docs, `contract.md`
 - Refresh or drop assertions against pre-migration characterization snapshots
-- Agentera 3.0: remove `skills/hej/` bridge and `references/v1-section-mapping.md`

package/bundle/skills/agentera/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: agentera
 description: >
-  The open protocol for turning AI agents into engineering teams. One Agentera
-  skill with twelve capabilities; per-capability prose lives in
+  Agentera agent engine for editor runtimes. One Agentera skill with twelve
+  capabilities; per-capability prose lives in
   `packages/cli/src/capabilities/<name>/instructions.ts` and the runtime serves
   it through `agentera prime --context <name> --format json`. Use this skill
   for /agentera, Agentera capability requests, and a complete user message
@@ -70,22 +70,25 @@ When a request arrives, route to the matching capability using the five-layer ro
 ### Prerequisite: Single-call installed CLI gate
 
 This gate is mandatory, but the gate and the orientation dashboard source are the same
-installed CLI invocation. For bare `/agentera` or bare `hej`, the first normal
-state-access tool call is:
+installed CLI invocation. For bare `/agentera` or bare `hej`, resolve the app home in
+one separate command, then run prime:
 
 ```bash
+RESOLVED_AGENTERA_HOME="$(npx -y agentera app-home)"
 npx -y agentera prime
 ```
 
+Never combine the app-home assignment with the same shell command that runs
+prime; shell expansion can otherwise turn an unset `AGENTERA_HOME` into
+`npx -y agentera` before the assignment takes effect.
+
 Resolve `RESOLVED_AGENTERA_HOME` with the app-home precedence `AGENTERA_HOME`
-when set, otherwise the platform data home. Do not run `glob`, `grep`, `read`,
-`ls`, `python`, `doctor`, `--help`, `registry.json`,
-or `.agentera-bundle.json` preflight checks before this call. The CLI owns app
-validation, v1 detection, profile detection, artifact condensation, and the
+when set, otherwise the platform data home from `agentera app-home`. Do not substitute
+the Linux-only `${XDG_DATA_HOME:-$HOME/.local/share}/agentera` fallback on macOS or
+Windows. Do not run `glob`, `grep`, `read`, `ls`, `python`, `doctor`, `--help`,
+`registry.json`, or `.agentera-bundle.json` preflight checks before this call. The CLI
+owns app validation, v1 detection, profile detection, artifact condensation, and the
 `source_contract` that tells the caller how to render the dashboard.
-Never combine the app-home assignment with the same shell command that expands
-the managed app script path; shell expansion can otherwise turn an unset
-`AGENTERA_HOME` into `npx -y agentera` before the assignment takes effect.
 
 If the command exits successfully, inspect the CLI-provided `bundle.status`
 installed-app status object. If its value is `fresh`, treat the installed app gate as passed
@@ -93,8 +96,24 @@ for that briefing and render from the output. The object includes
 `expectedVersion`, `expectedVersionSource`, `appHome`, `managedAppRoot`,
 `userDataRoot`, repair commands, and approval text.
 
+### User-facing update wording
+
+When `bundle.status` is `outdated` or doctor reports version-behind app files,
+the install is valid but older than expected. Use **update** language, not
+repair or broken-install framing.
+
+1. What happened: `Agentera app files are out of date.`
+2. What the preview did: `Nothing was changed.`
+3. What the recommended fix will do: `Update Agentera app files to the expected version in the normal Agentera directory.`
+4. What it will not do: `It will not edit your project files, shell startup files, or unknown directories.`
+
+Name both the operation and the command: for example, `app files outdated; run agentera upgrade`.
+Ask for explicit approval before writes with plain wording such as
+`Approve the Agentera app-file update at <directory>`.
+
 ### User-facing repair wording
 
+When `bundle.status` is `repair_needed`, files are missing, incomplete, or broken.
 Recovery and troubleshooting prompts must be plain enough for a non-technical
 user. Never ask the user to choose between technical install concepts, internal
 directory states, command-mode flags, or package-layout terms. Keep those as
@@ -140,28 +159,17 @@ the upgrade output, not from the old default directory. If the command executes
 fails before argparse, reports `invalid choice` for `prime`, or reports a status of
 `outdated`, `manual_review_needed`, missing-command, or repair-needed:
 
-- Say `Agentera found an old or broken local copy of itself.`
+- For `outdated` only: use the **update wording** section above (`Agentera app files are out of date`, approve an app-file **update**).
+- For `repair_needed`, missing-command, or broken-install states: use the **repair wording** section above (`old or broken local copy`, approve a **repair**).
+- For `manual_review_needed`: say Agentera needs a user decision before any writes.
 - Say whether the preview changed anything; preview commands change nothing.
 - State the safe recommendation in plain language before paths or commands.
-- Show the clone-free preview command from `bundle.dryRunCommand` when present:
-
-```bash
-npx -y agentera@latest doctor
-```
+- Show the clone-free preview command from `bundle.dryRunCommand` when present.
 
 Ask for explicit approval before writes. A normal affirmative response is
-acceptable only when it clearly authorizes the same Agentera repair and directory.
-If approved, apply:
-
-```bash
-npx -y agentera@latest prime
-```
-
-After apply, retry:
-
-```bash
-npx -y agentera prime
-```
+acceptable only when it clearly authorizes the same Agentera update, repair, or
+migration and directory. If approved, apply the matching `bundle.applyCommand` or
+channel-aware `agentera upgrade --yes` form, then retry `npx -y agentera prime`.
 
 If `AGENTERA_HOME` names the old default `$HOME/.agents/agentera`, no explicit
 `--install-root` was supplied, and `npx -y agentera` is
@@ -196,9 +204,10 @@ above must have already confirmed the installed CLI is usable.
 
 Routine commands are: `prime`, `state plan`, `state progress`, `state health`,
 `state todo`, `state decisions`, `state docs`, `state objective`, and
-`state experiments`. Top-level aliases for legacy commands remain during migration with stderr deprecation; see [audience-namespace-cli-migration.yaml](references/cli/audience-namespace-cli-migration.yaml) for the full list. Discovery and custom
-inspection remain available through `agentera schema --format json`
-(with legacy `describe` alias),
+`state experiments`. On the npm 3.x CLI, top-level `hej`, `describe`, `gate`, and
+routine-state names are removed; a smaller transitional alias set still forwards
+with stderr deprecation — see [audience-namespace-cli-migration.yaml](references/cli/audience-namespace-cli-migration.yaml). Discovery and custom
+inspection remain available through `agentera schema --format json`,
 `state query --list-artifacts`, and `state query <artifact-name> --format json|yaml`.
 Structured discovery includes an artifact-location contract with mapped paths,
 normal read commands, and raw-access boundaries; use that contract before
@@ -361,15 +370,14 @@ when supplied by the CLI.
 Do not replace the CLI-owned preview with manual artifact inspection,
 hand-written migration steps, or raw YAML reads. Only the apply step requires confirmation.
 
-The upgrade command is idempotent. It installs or updates Agentera app files
-when invoked through `uvx`, migrates v1 artifacts, wires runtime config to that
-app home, and removes fixable outdated v1 runtime artifacts.
-The artifacts phase migrates supported v1 Markdown files to YAML with backups
-after preview and confirmation. Package refreshes that run `npx skills remove`
-for v1 skill entries and `npx skills add` for `/agentera` remain explicit opt-in
-via `--update-packages`. `npx skills update` by itself updates only the visible
-skill; if `/agentera` then finds missing or out-of-date app files, run the
-plain-language repair preview above so upgrade updates the app and cleans up
+The upgrade command is idempotent. It installs or updates Agentera app files,
+migrates legacy Markdown artifacts to YAML when detected, wires runtime config
+to the app home, and removes fixable outdated runtime artifacts after preview
+and confirmation. Package refreshes that run `npx skills remove` for legacy
+standalone skill entries and `npx skills add` for `/agentera` remain explicit
+opt-in via `--update-packages`. `npx skills update` by itself updates only the
+visible skill; if `/agentera` then finds missing or out-of-date app files, run
+the plain-language repair preview above so upgrade updates the app and cleans up
 the old default directory when it is recoverable.
 
 ### Layer 1: Bare `/agentera` or bare `hej` — delegate to prime

package/bundle/skills/agentera/capabilities/hej/schemas/artifacts.yaml

@@ -60,7 +60,10 @@ ARTIFACTS:
     artifact_id: design
     local_role: consumes
     description: >-
-      Hej reads this for the briefing's design status.
+      Hej reads this for project design status metadata (exists, stale, missing).
+      Suite chrome styling uses protocol.yaml, prime --context capability prose,
+      and v2 app-home DESIGN.md when present — not the host project's design
+      artifact.
   11:
     id: A11
     artifact_id: profile

package/bundle/skills/agentera/capabilities/profilera/schemas/exit.yaml

@@ -12,7 +12,8 @@ EXIT_CONDITIONS:
     condition: flagged
     description: >-
       Profile generation or validation completed but with data quality
-      issues: extraction failed for one or more sources, prediction
+      issues: available runtime history was skipped without explicit
+      acceptance, extraction failed for one or more sources, prediction
       accuracy was below 3/5, or significant unresolved tensions were
       found.
     exit_signal: flagged

package/bundle/skills/agentera/capability_schema_contract.yaml

@@ -143,6 +143,34 @@ FIELD_RULES:
         - low
       description: Priority of this trigger entry for routing confidence.
 
+PROSE_CONVENTIONS:
+  description: >-
+    Authoring rules for capability behavioral instructions (Decision 71).
+    These conventions govern the prose in
+    packages/cli/src/capabilities/<name>/instructions.ts.
+  modal_vocabulary:
+    authority: RFC 2119
+    keywords:
+      - MUST
+      - MUST NOT
+      - SHOULD
+      - SHOULD NOT
+      - MAY
+    rule: >-
+      Capitalized keywords carry protocol force. Lowercase modal verbs
+      (should, must, may) remain ordinary English with no protocol force.
+      Use capitalized keywords when stating hard requirements, strong
+      recommendations, or optional behavior. Use lowercase modals in
+      natural prose that does not bind the agent.
+    rationale: >-
+      Weak models read capability instructions literally as user commands.
+      Deliberate modal vocabulary disambiguates intent: a capitalized MUST
+      signals a hard constraint, while lowercase "should" in descriptive
+      prose does not bind. This is the disambiguator, not the offender.
+    example: >-
+      Steps SHOULD be ordered by value/effort ratio. Each matrix cell
+      MUST be ≤15 words. A concept MAY reference external sources.
+
 PRIMITIVE_REFERENCE_FIELDS:
   description: >-
     Capability schema fields that reference protocol primitive groups. This