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

package/bundle/skills/agentera/SKILL.md

@@ -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

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