agentera 3.0.0-dev.2 → 3.0.0-dev.21

package/bundle/references/adapters/package-surface-characterization.md

@@ -1,48 +1,68 @@
-# Package Surface Characterization
+# Package surface characterization
 
-Characterized on 2026-05-06 before the PackageManifest registry migration. This file records current behavior only; it is not the registry design.
+Current Agentera 3.0 package behavior is owned by
+`references/adapters/package-registry.yaml` and the TypeScript
+`PackageRegistry` loader.
 
-The executable PackageManifest registry at `references/adapters/package-registry.yaml` and its loader `scripts/package_registry.py` now own the single source of truth for version surfaces, runtime package manifests, bundle surfaces, package commands, and docs targets. Validators, upgrade, and tests consume registry facts instead of duplicating constants.
+## Version matrix
 
-## Version-Bearing Surfaces
+`registry.json` `skills[0].version` is the persisted suite authority. Tracked
+suite mirrors must match it exactly. The npm package `version` may carry a
+development pre-release suffix, but its `X.Y.Z` core must match the suite:
 
-`registry.json` is the persisted suite-version authority. The current suite version is `2.2.0` at `skills[0].version`.
+| Surface | Selector |
+| --- | --- |
+| `packages/cli/package.json` | `version` (development pre-release) and `agentera.suiteVersion` (suite) |
+| `plugin.json` | `version` |
+| `.github/plugin/plugin.json` | `version` |
+| `.codex-plugin/plugin.json` | `version` |
+| `.cursor-plugin/plugin.json` | `version` |
+| `.opencode/plugins/agentera.js` | `AGENTERA_VERSION` |
+| `skills/agentera/SKILL.md` | frontmatter `version` |
 
-The current version-bearing surfaces are:
+`.opencode/package.json` is a runtime package manifest but intentionally has no
+suite-version field.
 
-| Surface | Kind | Current behavior |
-| --- | --- | --- |
-| `registry.json` | version-bearing surface | `skills[0].version` is the suite authority. |
-| `pyproject.toml` | version-bearing surface | `[project].version` matches the registry suite version. |
-| `plugin.json` | version-bearing surface and runtime package manifest | root Copilot manifest `version` matches the suite version. |
-| `.github/plugin/plugin.json` | version-bearing surface and runtime package manifest | repository Copilot manifest `version` matches the suite version. |
-| `.codex-plugin/plugin.json` | version-bearing surface and runtime package manifest | Codex manifest `version` matches the suite version. |
-| `.claude-plugin/marketplace.json` | version-bearing surface and runtime package manifest | `metadata.version` and every plugin entry version, including the legacy `hej` bridge, match the suite version. |
-| `.opencode/plugins/agentera.js` | version-bearing surface | `AGENTERA_VERSION` matches the registry suite version and drives the OpenCode command marker file `.agentera-version`. |
+`packages/cli/package.json#agentera.gitRef` identifies the last substantive
+package-source commit, not a later verification-only commit. Repository-local
+release validation requires that commit to exist and compares the package
+contract, compiled-source inputs, scripts, and bundled-data inputs against it.
+Only the package version and `gitRef`, project state, and the release validator
+implementing this check are excluded, avoiding a circular source reference.
 
-`.opencode/package.json` is intentionally not version-bearing. Its current behavior is runtime package manifest behavior only: it keeps `type: "module"`, `main`/`exports` pointing at `./plugins/agentera.js`, `dependencies["@opencode-ai/plugin"] == "1.14.33"`, and an `agentera` npm-loadable plugin metadata block, but it has no top-level `name` or `version` field.
+## Active runtime manifests
 
-## Package-Manager Command Surface
+The runtime manifest set covers exactly OpenCode, Codex, Cursor, and GitHub
+Copilot. Claude has no package or marketplace manifest.
 
-Upgrade package planning currently emits package-manager commands only for Claude Code and OpenCode runtime selections.
+| Runtime | Manifest sources |
+| --- | --- |
+| OpenCode | `.opencode/package.json` |
+| Codex | `.codex-plugin/plugin.json` |
+| Cursor | `.cursor-plugin/plugin.json` |
+| GitHub Copilot | `plugin.json`, `.github/plugin/plugin.json` |
 
-| Runtime | Action | Command argv | Skipped message | Dry-run behavior | Apply behavior with mocked command |
-| --- | --- | --- | --- | --- | --- |
-| `all` | `remove-legacy-skills` | `npx skills remove hej visionera resonera inspirera planera realisera inspektera optimera orkestrera visualisera dokumentera profilera -g -y` | `legacy skill removal skipped; pass --update-packages to run` | `--update-packages` without `--yes` leaves status `pending` and does not execute. | status becomes `applied`, message `package update completed`, and command result tails are recorded. |
-| `claude` | `install-agentera-skill` | `npx skills add jgabor/agentera -g -a claude-code --skill agentera -y` | `external package update skipped; pass --update-packages to run` | `--update-packages` without `--yes` leaves status `pending` and does not execute. | status becomes `applied`, message `package update completed`, and command result tails are recorded. |
-| `opencode` | `install-agentera-skill` | `npx skills add jgabor/agentera -g -a opencode --skill agentera -y` | `external package update skipped; pass --update-packages to run` | `--update-packages` without `--yes` leaves status `pending` and does not execute. | status becomes `applied`, message `package update completed`, and command result tails are recorded. |
+## npm bundle
 
-Write gating is preserved: `--update-packages` changes package items from `skipped` to `pending`, but package-manager commands execute only during apply mode behind `--yes`. Focused tests mock `subprocess.run`; no live package-manager call is part of this characterization.
+The self-contained npm package ships `dist/` plus `bundle/`. Bundle data
+includes the shared skill, contracts, references, release docs, and every
+runtime lifecycle/package source declared by the registry:
 
-## Bundle And Docs Drift Inventory
+- `.opencode/commands`, `.opencode/agents`, `.opencode/plugins`, and package manifest;
+- `.codex-plugin` and both Codex hook sources under `hooks/`;
+- `.cursor-plugin`, `.cursor/hooks.json`, and `.cursor/agents`;
+- Copilot root/repository manifests and `.github/hooks`;
+- `skills`, `references`, `registry.json`, README, upgrade guide, changelog,
+  design, and license.
 
-| Drift point | Surface class | Decision | Current behavior to preserve before migration |
-| --- | --- | --- | --- |
-| `pyproject.toml` force-includes and `scripts/agentera_upgrade.py` bundle lists duplicate the same shipped bundle directories and files. | bundle metadata surface | `standardize` | Keep both lists aligned now; later PackageManifest should own the list once. |
-| Lifecycle validation requires only the minimal shared runtime package paths (`skills`, `scripts`, `hooks`, `registry.json`, `plugin.json`, `pyproject.toml`, `README.md`) while pyproject and upgrade copy the larger distributable bundle. | runtime package manifest | `standardize` | Keep the validator as a minimum package-shape check now; later PackageManifest should separate minimal runtime metadata from full bundle includes. |
-| Runtime manifest `agentera.sharedPaths` includes `UPGRADE.md`, but `SUITE_BUNDLE_REQUIRED_PATHS` does not require it. | runtime package manifest | `standardize` | Keep current validator leniency now; later PackageManifest should make required shared paths explicit in one place. |
-| `.agentera/docs.yaml` `version_files` includes version-bearing surfaces and excludes `.opencode/package.json`. | version-bearing surface | `preserve` | Keep `.opencode/package.json` out of version checks because it is a runtime package manifest, not a suite version surface. |
-| `.opencode/package.json` is force-included and bundled, but it is not in docs `version_files`. | runtime package manifest | `preserve` | Keep packaging it without treating it as version-bearing. |
-| Upgrade package commands are represented as argv lists for Claude Code and OpenCode only; Codex and Copilot have runtime manifests but no package-manager command entries. | package-manager command surface | `preserve` | Keep command planning limited to currently managed package runtimes. |
-| `.claude-plugin/marketplace.json` carries a `hej` legacy bridge version alongside `agentera`. | version-bearing surface | `defer` | Keep the legacy bridge version aligned until a separate legacy-bridge removal or marketplace simplification task exists. |
-| Live package-manager behavior is not characterized by this task. | package-manager command surface | `defer` | Keep tests mocked; do not introduce live `npx skills` execution. |
+Packaging tests inspect `npm pack --dry-run --json --ignore-scripts` and fail if
+any declared runtime source disappears. The retired Claude manifest is also a
+negative assertion.
+
+## Package-manager boundary
+
+Lifecycle upgrade does not execute runtime-native package managers. Legacy
+portable-skill cleanup and the OpenCode portable-skill install specification
+remain argv-only package-registry records behind their existing update and
+approval gates. Native installation, enablement, authentication, and trust are
+user-owned actions.

package/bundle/references/adapters/runtime-adapter-characterization.md

@@ -1,79 +1,44 @@
-# Runtime Adapter Characterization
-
-Task 2 of `Deepen RuntimeAdapter Registry` records current behavior before any
-registry extraction. This is a characterization artifact, not the new registry.
-
-## Doctor Output
-
-Current JSON envelope fields are `schemaVersion`, `ok`, `installRoot`,
-`runtimes`, `summary`, and `smoke`. Each runtime result exposes `runtime`,
-`status`, `available`, `binary`, and `checks`. Each check exposes `name`,
-`status`, `message`, `source`, `path`, `gap`, and `details`.
-
-Primary pass messages by runtime:
-
-| Runtime | Primary check | Status | Message | Diagnostic label |
-|---------|---------------|--------|---------|------------------|
-| Claude Code | `CLAUDE_PLUGIN_ROOT` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
-| OpenCode | `plugin_file` | `pass` | `OpenCode plugin file is present` | none |
-| Copilot CLI | `AGENTERA_HOME` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
-| Codex CLI | `config.AGENTERA_HOME` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
-
-Current diagnostic labels that are intentionally public are `user_environment`,
-`runtime_config`, `bundle_packaging`, `command_drift`, `skill_path_drift`, and
-`validation_drift`.
-
-## Upgrade Planning
-
-Runtime-phase items currently expose `runtime`, `action`, `target`, `status`,
-and `message`; copy operations also expose `source`, and configure operations
-carry private `newText` until public JSON rendering strips it.
-
-Characterized runtime actions:
-
-| Runtime | Action | Target | Dry-run status | Apply behavior |
-|---------|--------|--------|----------------|----------------|
-| Claude Code | `configure` | none | `noop` | no local config write |
-| Codex CLI | `configure` | `~/.codex/config.toml` | `pending` | writes config, then reports `runtime update applied` |
-| Codex CLI | `copy-hooks` | `~/.codex/hooks.json` | `pending` | copies hooks, then reports `runtime update applied` |
-| Codex CLI | `copy-agent` | `~/.codex/agents/*.toml` | `pending` | copies managed capability descriptors, then reports `runtime update applied` |
-| Copilot CLI | `configure` | none | `noop` | no local config write; use per-invocation `AGENTERA_HOME` |
-| OpenCode | `copy-plugin` | `~/.config/opencode/plugins/agentera.js` | `pending` | copies plugin, then reports `runtime update applied` |
-| OpenCode | `copy-agent` | `~/.config/opencode/agents/*.md` | `pending` | copies managed capability descriptors, then reports `runtime update applied` |
-
-Package-phase items currently expose `runtime`, `action`, `command`, `status`,
-and `message`. Without `--update-packages`, package items are `skipped`; with it,
-Claude Code and OpenCode package commands become `pending` and apply through the
-external command runner. Copilot CLI and Codex CLI have no package command item in
-the current upgrade phase.
-
-## Lifecycle Validation
-
-Current pass output from `scripts/validate_lifecycle_adapters.py` is exactly:
-
-```text
-lifecycle adapter metadata ok
-```
-
-Current failure output begins with:
-
-```text
-lifecycle adapter validation failed:
-```
-
-Representative fail messages are characterized in `tests/test_runtime_adapters.py`:
-Copilot stale `lifecycleHooks`, unsupported hook event files, missing `preToolUse`
-artifact validation, Codex unsupported status values, malformed event containers,
-missing supported-event declarations, missing unsupported-event declarations, and
-missing `codex_hooks` limitation text.
-
-## Drift Inventory
-
-| Drift point | Decision | Before-migration handling |
-|-------------|----------|---------------------------|
-| duplicated runtime order appears in doctor, upgrade, and tests | `standardize` | Later registry extraction should define one runtime order and have consumers read it. |
-| upgrade package phase only manages Claude Code and OpenCode | `preserve` | This is current behavior, not a registry gap; Copilot CLI and Codex CLI package command support is separate future work. |
-| Codex supports hook events but shipped config wires only apply_patch validation | `preserve` | Keep the distinction between host support and shipped Agentera wiring. |
-| Claude lifecycle behavior is validated through native hook files, not lifecycle metadata | `defer` | Do not invent Claude lifecycle metadata in Task 2; decide during registry interface design. |
-| OpenCode session preload observes `session.created` but has no verified context injection path | `preserve` | Keep degraded preload semantics in docs and diagnostics. |
-| hard-gate docs only claim blocking for reconstructable OpenCode and Copilot candidates | `preserve` | Keep scoped claims; do not standardize to full hard-gate parity. |
+# Runtime adapter characterization
+
+The executable lifecycle contract is split deliberately:
+
+- `runtime-lifecycle-authority.yaml` owns active identities, surfaces, evidence,
+  support-floor rules, the Cursor alias, and retired inputs;
+- `runtime-lifecycle-adapters.yaml` owns the common eight-category adapter
+  claims and declared Agentera-managed resources;
+- `runtime-lifecycle-operation-contract.yaml` owns operation and ownership
+  semantics;
+- `runtime-retired-resources.yaml` owns bounded legacy cleanup;
+- `runtime-adapter-registry.yaml` retains host-event and behavioral parity facts
+  and must match the lifecycle authority's four identities.
+
+## Characterized identities
+
+| Runtime ID | Required host surface | Additional surface | Lifecycle source highlights |
+| --- | --- | --- | --- |
+| `opencode` | OpenCode host | — | plugin and single Agentera agent |
+| `codex` | Codex CLI | — | plugin hooks, copied hooks, capability TOML agents |
+| `cursor` | Cursor Agent CLI | Cursor IDE when observed | IDE plugin, hooks, and Agentera descriptor |
+| `copilot` | GitHub Copilot CLI | — | plugin manifests and lifecycle hooks |
+
+The inactive `cursor-agent` spelling identifies the Cursor CLI binary/source
+product only. Claude is absent from adapter records and can appear only in the
+retired cleanup or explicit historical-import contracts.
+
+## Diagnosis and remediation
+
+Every adapter reports `skills`, `plugins`, `hooks`, `agents`, `configuration`,
+`enablement`, `trust`, and `native_actions`. Evidence is read-only. Trust is
+never inferred. Managed repair is planned through the shared operation engine;
+native and user-owned work is returned as `action_required`.
+
+Preview has no side effects. Apply requires declared destinations and matching
+ownership-journal evidence, uses secure directory-relative publication on
+Linux, continues independent operations after failure, and converges on retry.
+
+## Validation
+
+`agentera check validate lifecycle-adapters` rejects identity drift, missing
+runtime/category/surface claims, unsafe destinations, unverified mandatory
+skills, missing package manifests, unbundled lifecycle sources, version drift,
+retired Claude manifests, and stale runtime-specific hook claims.

package/bundle/references/adapters/runtime-adapter-registry.yaml

@@ -1,88 +1,11 @@
 schema_version: agentera.runtimeAdapterRegistry.v1
-runtime_order:
-  - claude
+lifecycle_authority: references/adapters/runtime-lifecycle-authority.yaml
+adapter_record_order:
   - opencode
   - copilot
   - codex
   - cursor
-  - cursor-agent
 records:
-  - identity:
-      runtime_id: claude
-      display_name: Claude Code
-      adapter_family: native-plugin
-      support_status: supported
-    host_detection:
-      binary_names:
-        - claude
-      host_config_locations:
-        - CLAUDE_PLUGIN_ROOT
-      availability_probe_label: runtime_binary
-    lifecycle_events:
-      supported_events:
-        - PreToolUse
-        - PostToolUse
-        - UserPromptSubmit
-        - SessionStart
-        - Stop
-        - SubagentStop
-      unsupported_events: []
-      event_status:
-        PreToolUse: native
-        PostToolUse: native
-        UserPromptSubmit: native
-        SessionStart: native
-        Stop: native
-        SubagentStop: native
-      limitations:
-        - Claude lifecycle behavior is validated through native hook files rather than lifecycle metadata.
-    artifact_validation:
-      validation_events:
-        - PreToolUse
-      hard_gate_claims:
-        - Native hook files can run artifact validation before tool writes.
-      payload_reconstruction_limitations: []
-    subagent_dispatch:
-      mechanism: Claude Code native subagent dispatch
-      setup_targets: []
-      descriptor_sources: []
-      invocation_pattern: Use the host Task/subagent surface with the selected Agentera capability context.
-      tool_configuration: none
-      limitations:
-        - Agentera does not install per-capability Claude descriptors in this package phase.
-    config_targets:
-      runtime_config_files: []
-      hook_targets:
-        - .claude-plugin/marketplace.json
-      plugin_targets:
-        - skills/*/.claude-plugin/plugin.json
-      environment_exports:
-        - CLAUDE_PLUGIN_ROOT
-      write_safety_labels:
-        - Claude Code plugin installs expose the app home without local config writes
-    diagnostics:
-      check_names:
-        - CLAUDE_PLUGIN_ROOT
-      status_labels:
-        - pass
-        - warn
-        - fail
-        - skip
-      gap_labels:
-        - runtime_config
-        - user_environment
-      primary_messages:
-        - runtime can reach shared Agentera helper scripts
-        - Claude Code plugin root is not present in this process environment
-    documentation_claims:
-      reference_paths:
-        - references/adapters/runtime-feature-parity.md
-      parity_claims:
-        - Claude Code uses native plugin and hook surfaces.
-      install_claims:
-        - Claude Code plugin installs expose the app home without local config writes.
-      known_drifts:
-        - Claude lifecycle behavior is validated through native hook files, not lifecycle metadata.
   - identity:
       runtime_id: opencode
       display_name: OpenCode
@@ -98,7 +21,6 @@ records:
     lifecycle_events:
       supported_events:
         - shell.env
-        - chat.message
         - tool.execute.before
         - tool.execute.after
         - experimental.session.compacting
@@ -107,7 +29,6 @@ records:
       unsupported_events: []
       event_status:
         shell.env: supported
-        chat.message: supported
         tool.execute.before: supported
         tool.execute.after: supported
         experimental.session.compacting: supported
@@ -115,7 +36,6 @@ records:
         session.idle: supported_via_event
       limitations:
         - OpenCode session preload observes session.created but has no verified context injection path.
-        - OpenCode docs omit chat.message, but the exported plugin Hooks interface defines it.
         - OpenCode compaction context is bounded to CLI-first Agentera summaries.
     artifact_validation:
       validation_events:
@@ -125,12 +45,12 @@ records:
       payload_reconstruction_limitations:
         - Sparse payloads and apply_patch patchText without reconstructed full content are allowed.
     subagent_dispatch:
-      mechanism: OpenCode .opencode/agents descriptors
+      mechanism: OpenCode .opencode/agents single primary agent (D73)
       setup_targets:
         - ~/.config/opencode/agents
       descriptor_sources:
-        - .opencode/agents/*.md
-      invocation_pattern: Use @<capability> for the installed Agentera capability descriptor.
+        - .opencode/agents/agentera.md
+      invocation_pattern: Use @agentera for the single Agentera primary agent; routing via skill, dispatch to general subagent.
       tool_configuration: per_agent_permission
       limitations:
         - OpenCode descriptor bootstrap is file-based and preserves user-owned descriptor collisions.
@@ -152,6 +72,8 @@ records:
         - opencode_managed_commands
         - opencode_skill_paths
         - bundled_support_references
+        - profile_dir_deprecated
+        - profile_dir_schema_literal
       status_labels:
         - pass
         - warn
@@ -174,21 +96,23 @@ records:
         - OpenCode Agentera skill paths are missing or broken
         - bundled support references validate separately from installer status
         - bundled reference validation mismatch found despite installer status
+        - profile dir env var is current
+        - v2 env var PROFILERA_PROFILE_DIR detected; run `agentera upgrade` to migrate to AGENTERA_PROFILE_DIR
+        - OpenCode plugin profile-dir schema is current
+        - OpenCode plugin source uses unmigrated profile-dir schema literal (PROFILERA_PROFILE_DIR without AGENTERA_PROFILE_DIR); run `agentera upgrade`
     documentation_claims:
       reference_paths:
         - references/adapters/runtime-feature-parity.md
         - references/adapters/opencode.md
       parity_claims:
         - Blocks invalid reconstructable artifact candidates.
-        - Routes exact bare text hej through chat.message to the bundled Agentera dashboard path.
       install_claims:
         - OpenCode plugin is copied to the native plugin path.
       known_drifts:
         - OpenCode session preload observes session.created but has no verified context injection path.
-        - OpenCode docs omit chat.message even though the plugin source Hooks interface exposes it.
   - identity:
       runtime_id: copilot
-      display_name: Copilot CLI
+      display_name: GitHub Copilot
       adapter_family: portable-plugin
       support_status: supported
     host_detection:
@@ -217,7 +141,7 @@ records:
         postToolUse: supported
         errorOccurred: supported
       limitations:
-        - Profilera exposes bounded corpus metadata limits with missing source families.
+        - Profile exposes bounded corpus metadata limits with missing source families.
     artifact_validation:
       validation_events:
         - preToolUse
@@ -270,9 +194,9 @@ records:
         - Upgrade runtime configure is noop; shell rc paths in host_detection are doctor diagnostic probes only.
   - identity:
       runtime_id: codex
-      display_name: Codex CLI
+      display_name: Codex
       adapter_family: portable-plugin
-      support_status: degraded
+      support_status: supported
     host_detection:
       binary_names:
         - codex
@@ -357,11 +281,12 @@ records:
         - Codex supports hook events but shipped config wires only apply_patch validation.
   - identity:
       runtime_id: cursor
-      display_name: Cursor IDE
+      display_name: Cursor
       adapter_family: native-plugin
       support_status: supported
     host_detection:
       binary_names:
+        - cursor-agent
         - cursor
       host_config_locations:
         - AGENTERA_HOME
@@ -397,7 +322,7 @@ records:
         stop: supported
       limitations:
         - Cloud agents are unsupported in v1; repo hooks and managed agents target local IDE sessions only.
-        - Bare text hej routing is metadata-only; sessionStart injects context but does not rewrite prompts.
+        - Bare text /agentera routing is metadata-only; sessionStart injects context but does not rewrite prompts.
     artifact_validation:
       validation_events:
         - preToolUse
@@ -406,12 +331,12 @@ records:
       payload_reconstruction_limitations:
         - Malformed, sparse, or non-reconstructable tool_input payloads are allowed.
     subagent_dispatch:
-      mechanism: Cursor .cursor/agents descriptors
+      mechanism: Cursor .cursor/agents single agent descriptor (D73)
       setup_targets:
         - .cursor/agents
       descriptor_sources:
-        - .cursor/agents/*.md
-      invocation_pattern: Use the Cursor agent picker or @-mention the installed Agentera capability descriptor.
+        - .cursor/agents/agentera.md
+      invocation_pattern: Use the Cursor agent picker or @-mention the single Agentera agent; routing via skill, dispatch to general subagent.
       tool_configuration: global_full_access
       limitations:
         - Cloud agent sessions do not load project hooks or managed agents in v1.
@@ -460,89 +385,3 @@ records:
       known_drifts:
         - Release tagging and marketplace publication remain blocked pending broader release closeout despite passed live preToolUse Write smoke.
         - Cloud agents are unsupported in v1.
-  - identity:
-      runtime_id: cursor-agent
-      display_name: Cursor Agent CLI
-      adapter_family: portable-cli
-      support_status: degraded
-    host_detection:
-      binary_names:
-        - cursor-agent
-        - agent
-      host_config_locations:
-        - AGENTERA_HOME
-        - ~/.bashrc
-        - ~/.zshrc
-        - ~/.config/fish/config.fish
-      availability_probe_label: runtime_binary
-    lifecycle_events:
-      supported_events:
-        - sessionStart
-        - sessionEnd
-        - preToolUse
-        - postToolUse
-      unsupported_events:
-        - subagentStart
-        - subagentStop
-        - beforeSubmitPrompt
-        - preCompact
-        - stop
-      event_status:
-        sessionStart: degraded
-        sessionEnd: degraded
-        preToolUse: degraded
-        postToolUse: degraded
-      limitations:
-        - CLI sessions may not inherit IDE sessionStart env; persistent shell configuration is a fallback only when shell-tool smoke fails.
-        - Non-interactive print mode may hang after completion in some host builds; eval and smoke harnesses use bounded timeouts.
-        - Cloud agents are unsupported in v1.
-    artifact_validation:
-      validation_events:
-        - preToolUse
-      hard_gate_claims:
-        - CLI hook parity is degraded relative to IDE; hard-gate claims follow IDE smoke evidence only.
-      payload_reconstruction_limitations:
-        - CLI may omit hook wiring entirely when launched outside a Cursor workspace with project hooks.
-    subagent_dispatch:
-      mechanism: Cursor Agent CLI host-managed dispatch
-      setup_targets: []
-      descriptor_sources: []
-      invocation_pattern: Use cursor-agent with explicit capability context; managed .cursor/agents descriptors apply only when the workspace is loaded.
-      tool_configuration: global_full_access
-      limitations:
-        - Agentera does not install per-capability cursor-agent descriptors separately from IDE managed agents.
-    config_targets:
-      runtime_config_files: []
-      hook_targets: []
-      plugin_targets: []
-      environment_exports:
-        - AGENTERA_HOME
-      write_safety_labels:
-        - configure
-    diagnostics:
-      check_names:
-        - AGENTERA_HOME
-        - cursor-agent
-      status_labels:
-        - pass
-        - warn
-        - fail
-        - skip
-      gap_labels:
-        - runtime_config
-        - user_environment
-      primary_messages:
-        - runtime can reach shared Agentera helper scripts
-        - cursor-agent binary is not on PATH
-        - cursor-agent helper access depends on AGENTERA_HOME or shell rc configuration
-    documentation_claims:
-      reference_paths:
-        - references/adapters/runtime-feature-parity.md
-        - references/adapters/cursor.md
-      parity_claims:
-        - cursor-agent supports eval_skills --runtime cursor-agent print-mode dispatch.
-      install_claims:
-        - cursor-agent inherits IDE hook wiring only when run inside a workspace with installed Cursor surfaces.
-      known_drifts:
-        - CLI hook and session env parity is degraded relative to Cursor IDE.
-        - Bare text hej routing is metadata-only like Claude, Copilot, and Codex.