agentera 3.0.0-dev.4 → 3.0.0-dev.41

package/dist/validate/vocabularyAuthority.js

@@ -0,0 +1,305 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolvePath } from "../core/paths.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { loadYamlMappingFile } from "../core/yaml.js";
+import { APP_MANUAL_REVIEW_NEEDED, APP_MIGRATION_NEEDED, APP_OUTDATED, APP_REPAIR_NEEDED, APP_UP_TO_DATE, } from "../upgrade/doctor.js";
+import { validateGlossaryEntryContract } from "../registries/glossaryEntryContract.js";
+/**
+ * Validate vocabulary authority YAML contracts (Decision 54 lifecycle status
+ * vocabulary, Decision 57 first_invocation_read, update channels, index order).
+ * Emits the same delegated validate envelope shape as lifecycle-adapters.
+ */
+const EXPECTED_STATUSES = [
+    "up_to_date",
+    "outdated",
+    "repair_needed",
+    "migration_needed",
+    "manual_review_needed",
+    "ready_to_apply",
+    "applied",
+    "no_changes_needed",
+];
+const EXPECTED_VERBS = ["install", "repair", "update", "migrate", "upgrade", "refresh"];
+const EXPECTED_LIFECYCLE_CONSUMERS = ["doctor", "status", "upgrade", "docs", "tests"];
+const EXPECTED_CHANNELS = ["stable", "development"];
+const EXPECTED_CHANNEL_CONSUMERS = ["upgrade", "doctor", "prime", "docs", "tests"];
+function rootDefault() {
+    return resolveSourceRoot();
+}
+function authorityPath(root, relative) {
+    return path.join(root, relative);
+}
+function canonicalStatuses(authority) {
+    return new Set(Object.keys(authority.canonical_statuses));
+}
+function rejectedLifecycleStatusValues(authority) {
+    const statuses = authority.canonical_statuses;
+    const verbs = authority.operation_verbs;
+    const deprecated = Object.values(statuses).flatMap((entry) => {
+        const aliases = entry.deprecated_aliases;
+        return Array.isArray(aliases) ? aliases : [];
+    });
+    const nonLifecycleVerbs = Object.entries(verbs)
+        .filter(([, entry]) => entry.lifecycle_allowed === false)
+        .map(([name]) => name);
+    return new Set([...deprecated, ...nonLifecycleVerbs].map(String));
+}
+function validateLifecycleAuthority(root) {
+    const errors = [];
+    const p = authorityPath(root, "references/cli/app-lifecycle-vocabulary.yaml");
+    let authority;
+    try {
+        authority = loadYamlMappingFile(p); // cast: YAML parse IO boundary
+    }
+    catch (exc) {
+        return [`app-lifecycle-vocabulary.yaml: ${exc.message}`];
+    }
+    if (!Array.isArray(authority.canonical_status_order) || authority.canonical_status_order.length === 0) {
+        errors.push("app-lifecycle-vocabulary.yaml: canonical_status_order is required");
+    }
+    else if (JSON.stringify(authority.canonical_status_order) !== JSON.stringify([...EXPECTED_STATUSES])) {
+        errors.push("app-lifecycle-vocabulary.yaml: canonical_status_order drifted from Decision 54 pin");
+    }
+    const statusKeys = Object.keys(authority.canonical_statuses);
+    if (JSON.stringify(statusKeys) !== JSON.stringify([...EXPECTED_STATUSES])) {
+        errors.push("app-lifecycle-vocabulary.yaml: canonical_statuses keys drifted from Decision 54 pin");
+    }
+    for (const status of EXPECTED_STATUSES) {
+        const entry = authority.canonical_statuses[status];
+        if (!entry || !String(entry.concept ?? "").trim() || !String(entry.definition ?? "").trim()) {
+            errors.push(`app-lifecycle-vocabulary.yaml: canonical status '${status}' is incomplete`);
+        }
+    }
+    const aliasToStatus = new Map();
+    for (const [status, raw] of Object.entries(authority.canonical_statuses)) {
+        for (const alias of raw.deprecated_aliases) {
+            aliasToStatus.set(alias, status);
+        }
+    }
+    const expectedAliases = {
+        fresh: "up_to_date",
+        stale: "outdated",
+        refresh_required: "repair_needed",
+        fixed: "applied",
+        noop: "no_changes_needed",
+    };
+    for (const [alias, status] of Object.entries(expectedAliases)) {
+        if (aliasToStatus.get(alias) !== status) {
+            errors.push(`app-lifecycle-vocabulary.yaml: deprecated alias '${alias}' must map to '${status}'`);
+        }
+    }
+    const doctorAllowed = new Set(authority.consumers.doctor.may_emit_statuses);
+    const observed = [
+        APP_UP_TO_DATE,
+        APP_OUTDATED,
+        APP_REPAIR_NEEDED,
+        APP_MIGRATION_NEEDED,
+        APP_MANUAL_REVIEW_NEEDED,
+    ];
+    for (const status of observed) {
+        if (!canonicalStatuses(authority).has(status)) {
+            errors.push(`doctor constant '${status}' is not a canonical lifecycle status`);
+        }
+        else if (!doctorAllowed.has(status)) {
+            errors.push(`doctor consumer may not emit canonical status '${status}'`);
+        }
+        else if (rejectedLifecycleStatusValues(authority).has(status)) {
+            errors.push(`doctor constant '${status}' is a rejected lifecycle alias or verb`);
+        }
+    }
+    if (!Array.isArray(authority.consumer_order) || authority.consumer_order.length === 0) {
+        errors.push("app-lifecycle-vocabulary.yaml: consumer_order is required");
+    }
+    else if (JSON.stringify(authority.consumer_order) !== JSON.stringify([...EXPECTED_LIFECYCLE_CONSUMERS])) {
+        errors.push("app-lifecycle-vocabulary.yaml: consumer_order drifted from Decision 54 pin");
+    }
+    const allowedStatuses = new Set(EXPECTED_STATUSES);
+    const allowedVerbs = new Set(EXPECTED_VERBS);
+    for (const consumer of EXPECTED_LIFECYCLE_CONSUMERS) {
+        const entry = authority.consumers[consumer];
+        if (!entry) {
+            errors.push(`app-lifecycle-vocabulary.yaml: missing consumer '${consumer}'`);
+            continue;
+        }
+        if (entry.may_define_new_statuses !== false) {
+            errors.push(`app-lifecycle-vocabulary.yaml: consumer '${consumer}' must not define new statuses`);
+        }
+        for (const status of entry.may_emit_statuses ?? []) {
+            if (!allowedStatuses.has(status)) {
+                errors.push(`app-lifecycle-vocabulary.yaml: consumer '${consumer}' emits unknown status '${status}'`);
+            }
+        }
+        for (const verb of entry.may_use_verbs ?? []) {
+            if (!allowedVerbs.has(verb)) {
+                errors.push(`app-lifecycle-vocabulary.yaml: consumer '${consumer}' uses unknown verb '${verb}'`);
+            }
+        }
+    }
+    const delegation = authority.docs_delegation;
+    if (delegation?.document !== "references/cli/vocabulary.md" ||
+        delegation?.required_anchor !== "App lifecycle status vocabulary" ||
+        delegation?.authority_path !== "references/cli/app-lifecycle-vocabulary.yaml") {
+        errors.push("app-lifecycle-vocabulary.yaml: docs_delegation contract drifted");
+    }
+    return errors;
+}
+function validateUpdateChannelsAuthority(root) {
+    const errors = [];
+    const p = authorityPath(root, "references/cli/update-channels.yaml");
+    let authority;
+    try {
+        authority = loadYamlMappingFile(p); // cast: YAML parse IO boundary
+    }
+    catch (exc) {
+        return [`update-channels.yaml: ${exc.message}`];
+    }
+    if (authority.default_channel !== "stable") {
+        errors.push("update-channels.yaml: default_channel must be stable");
+    }
+    if (JSON.stringify(authority.channel_order) !== JSON.stringify([...EXPECTED_CHANNELS])) {
+        errors.push("update-channels.yaml: channel_order drifted");
+    }
+    const stable = authority.channels.stable;
+    const development = authority.channels.development;
+    if (!stable || !development) {
+        errors.push("update-channels.yaml: stable and development channels are required");
+    }
+    else {
+        const stableNpm = stable.resolution?.npm;
+        const devNpm = development.resolution?.npm;
+        if (stableNpm?.dist_tag !== "latest" || devNpm?.dist_tag !== "next") {
+            errors.push("update-channels.yaml: npm dist_tag pins drifted");
+        }
+        if (!String(stableNpm?.update_command ?? "").includes("@latest")) {
+            errors.push("update-channels.yaml: stable npm update_command must reference @latest");
+        }
+        if (!String(devNpm?.update_command ?? "").includes("@next")) {
+            errors.push("update-channels.yaml: development npm update_command must reference @next");
+        }
+        if (development.resolution?.git && development.resolution.git) {
+            const devGit = development.resolution.git;
+            if (devGit.supported !== false) {
+                errors.push("update-channels.yaml: development git resolution must be unsupported");
+            }
+        }
+    }
+    if (!Array.isArray(authority.consumer_order)) {
+        errors.push("update-channels.yaml: consumer_order is required");
+    }
+    else if (JSON.stringify(authority.consumer_order) !== JSON.stringify([...EXPECTED_CHANNEL_CONSUMERS])) {
+        errors.push("update-channels.yaml: consumer_order drifted");
+    }
+    const delegation = authority.docs_delegation;
+    if (delegation?.document !== "references/cli/vocabulary.md" ||
+        delegation?.required_anchor !== "Update channels" ||
+        delegation?.authority_path !== "references/cli/update-channels.yaml") {
+        errors.push("update-channels.yaml: docs_delegation contract drifted");
+    }
+    return errors;
+}
+function validateInstructionContract(root) {
+    const errors = [];
+    const p = authorityPath(root, "references/cli/capability-instruction-contract.yaml");
+    let authority;
+    try {
+        authority = loadYamlMappingFile(p); // cast: YAML parse IO boundary
+    }
+    catch (exc) {
+        return [`capability-instruction-contract.yaml: ${exc.message}`];
+    }
+    const firstRead = authority.first_invocation_read;
+    if (!firstRead) {
+        errors.push("capability-instruction-contract.yaml: first_invocation_read block is required");
+        return errors;
+    }
+    const allowed = firstRead.allowed_values;
+    if (!allowed || typeof allowed.prime_context !== "object") {
+        errors.push("capability-instruction-contract.yaml: first_invocation_read.allowed_values.prime_context is required");
+    }
+    else {
+        const meaning = String(allowed.prime_context.meaning ?? "");
+        if (!meaning.includes("agentera prime --context")) {
+            errors.push("capability-instruction-contract.yaml: prime_context obligation must reference agentera prime --context");
+        }
+    }
+    if (firstRead.default_rule !== "prime_context") {
+        errors.push("capability-instruction-contract.yaml: first_invocation_read.default_rule must be prime_context");
+    }
+    const cliMeta = authority.current_state?.cli_metadata;
+    if (cliMeta?.field !== "first_invocation_read") {
+        errors.push("capability-instruction-contract.yaml: cli_metadata.field must be first_invocation_read");
+    }
+    const delegation = authority.docs_delegation;
+    if (delegation?.document !== "references/cli/vocabulary.md" ||
+        delegation?.required_anchor !== "Capability instruction contract" ||
+        delegation?.authority_path !== "references/cli/capability-instruction-contract.yaml") {
+        errors.push("capability-instruction-contract.yaml: docs_delegation contract drifted");
+    }
+    return errors;
+}
+function validateVocabularyIndex(root) {
+    const errors = [];
+    const p = authorityPath(root, "references/cli/vocabulary-index.yaml");
+    let index;
+    try {
+        index = loadYamlMappingFile(p); // cast: YAML parse IO boundary
+    }
+    catch (exc) {
+        return [`vocabulary-index.yaml: ${exc.message}`];
+    }
+    const order = index.authority_order;
+    if (!Array.isArray(order)) {
+        return ["vocabulary-index.yaml: authority_order is required"];
+    }
+    const lifecycleIdx = order.indexOf("references/cli/app-lifecycle-vocabulary.yaml");
+    const channelsIdx = order.indexOf("references/cli/update-channels.yaml");
+    const bundleIdx = order.indexOf("references/cli/bundle-skill-vocabulary.yaml");
+    if (lifecycleIdx < 0 || channelsIdx < 0 || bundleIdx < 0) {
+        errors.push("vocabulary-index.yaml: authority_order missing required vocabulary authorities");
+    }
+    else if (!(lifecycleIdx < channelsIdx && channelsIdx < bundleIdx)) {
+        errors.push("vocabulary-index.yaml: authority_order must place lifecycle before channels before bundle");
+    }
+    const vocabularyMd = authorityPath(root, "references/cli/vocabulary.md");
+    if (!fs.existsSync(vocabularyMd)) {
+        errors.push("references/cli/vocabulary.md: missing vocabulary prose delegation surface");
+        return errors;
+    }
+    const vocabulary = fs.readFileSync(vocabularyMd, "utf8");
+    const lifecycleSection = vocabulary.split("### App lifecycle status vocabulary")[1]?.split("### Update channels", 1)[0] ?? "";
+    if (!lifecycleSection.includes("references/cli/app-lifecycle-vocabulary.yaml") ||
+        !lifecycleSection.includes("machine-readable authority")) {
+        errors.push("references/cli/vocabulary.md: app lifecycle section must delegate to YAML authority");
+    }
+    const channelsSection = vocabulary.split("### Update channels")[1]?.split("### Bundle and SKILL.md vocabulary", 1)[0] ?? "";
+    if (!channelsSection.includes("references/cli/update-channels.yaml") ||
+        !channelsSection.includes("machine-readable authority")) {
+        errors.push("references/cli/vocabulary.md: update channels section must delegate to YAML authority");
+    }
+    return errors;
+}
+export function validateVocabularyAuthority(root = rootDefault()) {
+    const resolved = resolvePath(root);
+    return [
+        ...validateLifecycleAuthority(resolved),
+        ...validateUpdateChannelsAuthority(resolved),
+        ...validateInstructionContract(resolved),
+        ...validateVocabularyIndex(resolved),
+        ...validateGlossaryEntryContract(authorityPath(resolved, "references/artifacts/glossary-entry-contract.yaml")),
+    ];
+}
+export function vocabularyAuthorityMain(opts = {}) {
+    const root = resolvePath(opts.root ?? rootDefault());
+    const out = opts.out ?? ((line) => process.stdout.write(line + "\n"));
+    const errors = validateVocabularyAuthority(root);
+    if (errors.length > 0) {
+        out("vocabulary authority validation failed:");
+        for (const error of errors)
+            out(`- ${error}`);
+        return 1;
+    }
+    out("vocabulary authority ok");
+    return 0;
+}
+//# sourceMappingURL=vocabularyAuthority.js.map

package/dist/validate/vocabularyAuthority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabularyAuthority.js","sourceRoot":"","sources":["../../../../../home/jgabor/git/agentera.release-publish-dev40/packages/cli/src/validate/vocabularyAuthority.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,24 +1,20 @@
 {
   "name": "agentera",
-  "version": "3.0.0-dev.4",
-  "description": "Agentera app-home protocol and CLI (TypeScript)",
-  "type": "module",
-  "license": "Apache-2.0",
-  "author": "Jonathan Gabor",
-  "homepage": "https://github.com/jgabor/agentera",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jgabor/agentera.git",
-    "directory": "packages/cli"
-  },
+  "version": "3.0.0-dev.41",
+  "description": "One CLI, many capabilities: project state, artifact validation, and capability routing for AI coding agents",
   "keywords": [
     "agentera",
     "agents",
     "cli",
     "orchestration"
   ],
-  "engines": {
-    "node": ">=22"
+  "homepage": "https://github.com/jgabor/agentera",
+  "license": "Apache-2.0",
+  "author": "Jonathan Gabor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgabor/agentera.git",
+    "directory": "packages/cli"
   },
   "bin": {
     "agentera": "dist/bin/agentera.js"
@@ -27,23 +23,38 @@
     "dist",
     "bundle"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepack": "tsc -p tsconfig.json && node scripts/copy-bundle.mjs",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "bundle:data": "node scripts/copy-bundle.mjs",
-    "publish:dev": "npm run build && npm run bundle:data && npm publish --tag next"
-  },
-  "agentera": {
-    "suiteVersion": "2.7.6",
-    "gitRef": "v3.0.0-dev.4"
-  },
+  "type": "module",
   "publishConfig": {
     "access": "public",
     "tag": "next"
   },
+  "scripts": {
+    "build": "node scripts/build-package.mjs",
+    "prepack": "node scripts/reject-direct-prepack.mjs",
+    "test": "pnpm run test:source",
+    "test:source": "node scripts/verify-lane.mjs source",
+    "test:stress": "node scripts/verify-lane.mjs stress",
+    "test:performance": "node scripts/verify-lane.mjs performance",
+    "test:performance:integration": "node test/integration/performanceOwner.integration.mjs",
+    "test:watch": "vp test watch --config vite.config.ts",
+    "verify:package": "node scripts/verify-lane.mjs package",
+    "verify:generated-overlap": "node scripts/verify-generated-overlap.mjs",
+    "generated:cleanup": "node scripts/build-package.mjs --cleanup",
+    "pack:dry-run": "node scripts/pack-package.mjs --dry-run",
+    "release:prepare": "node scripts/publication-transaction.mjs prepare development",
+    "verify:targeted": "node scripts/verify-lane.mjs policy targeted",
+    "verify:precommit": "node scripts/verify-lane.mjs policy precommit",
+    "verify:fast": "node scripts/verify-lane.mjs policy fast",
+    "verify:local": "node scripts/verify-lane.mjs policy local",
+    "verify:merge": "node scripts/verify-lane.mjs policy merge",
+    "verify:scheduled": "node scripts/verify-lane.mjs policy scheduled",
+    "verify:release": "node scripts/verify-lane.mjs policy release",
+    "lint": "vp lint",
+    "fmt": "vp fmt",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "bundle:data": "node scripts/build-package.mjs",
+    "publish:dev": "set -a; [ -f ../../.env ] && . ../../.env; set +a; node scripts/publication-transaction.mjs publish development --authorize"
+  },
   "dependencies": {
     "smol-toml": "^1.3.1",
     "yaml": "^2.8.3"
@@ -51,6 +62,14 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vite": "^6.3.5",
+    "vite-plus": "^0.1.22"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "agentera": {
+    "suiteVersion": "3.0.0",
+    "gitRef": "46aef0efa1bb70793cb79786a6363062c2b8cf1c"
   }
 }

package/bundle/references/adapters/cursor.md

@@ -1,213 +0,0 @@
-# Cursor adapter reference
-
-Agentera v1 ships Cursor as two registry identities:
-
-| Identity | Host | Support status |
-| -------- | ---- | -------------- |
-| `cursor` | Cursor IDE (Composer / Agent) | supported |
-| `cursor-agent` | Cursor Agent CLI (`cursor-agent`, `agent`) | degraded |
-
-Decision 63 owns v1 scope. Cloud agents are unsupported. Bare text `hej` routing
-stays metadata-only like Claude, Copilot, and Codex.
-
-## Quick install
-
-**Local plugin (no Marketplace listing required)**
-
-```bash
-git clone https://github.com/jgabor/agentera.git ~/.cursor/plugins/local/agentera
-# or: ln -s /path/to/agentera ~/.cursor/plugins/local/agentera
-```
-
-Restart Cursor or run **Developer: Reload Window**. The plugin root must contain
-`.cursor-plugin/plugin.json`. Agentera is not published to the Cursor Marketplace
-yet; use this manual local path or Cursor's local plugin loading UI instead.
-
-The plugin loads skills, managed capability agents, and plugin hooks. When you open
-a project that is not an Agentera install root, `sessionStart` exports
-`AGENTERA_HOME` from the plugin checkout (including a plugin-root fallback when env
-and project walk-up do not resolve a managed root).
-
-**Portable skill plus project upgrade**
-
-```bash
-npx skills add jgabor/agentera -g -a cursor --skill agentera -y
-uvx --from git+https://github.com/jgabor/agentera agentera upgrade --project "$PWD" --runtime cursor --yes
-uvx --from git+https://github.com/jgabor/agentera agentera doctor --runtime cursor
-```
-
-Use the plugin path for a user-global install. Use upgrade when you need
-project-committed `.cursor/hooks.json` and `.cursor/agents/` copies. Both paths can
-be combined.
-
-From a clone, replace `uvx … agentera` with `uv run scripts/agentera`. User-facing
-install steps also live in [`README.md`](../../README.md) and
-[`UPGRADE.md`](../../UPGRADE.md).
-
-## Repo-native surfaces
-
-This repository dogfoods committed Cursor surfaces:
-
-- `.cursor/hooks.json` — sessionStart env export, preToolUse hard gate, postToolUse advisory validation
-- `.cursor/agents/*.md` — twelve managed capability descriptors
-- `.cursor-plugin/plugin.json` — marketplace submission-ready manifest
-
-Hooks resolve helper scripts through `uv run hooks/...` from the project root.
-`sessionStart` exports `AGENTERA_HOME` through Cursor hook JSON (`env`) before
-subsequent hook executions run.
-
-## AGENTERA_HOME wiring
-
-Primary path: `hooks/cursor_session_start.py` resolves the install root from
-`AGENTERA_HOME`, project walk-up, or the plugin/checkout root (`hooks/` parent)
-when the hook runs from a plugin install, then returns
-`{"env": {"AGENTERA_HOME": "<root>"}}` plus optional `additional_context` from
-the shared session digest.
-
-Fallback: `scripts/setup_cursor.py` reports persistent shell configuration only
-when live shell-tool smoke proves session env does not propagate to CLI
-subprocesses. Agentera does not write shell rc files by default.
-
-## Artifact validation
-
-| Surface | Behavior | Claim status |
-| ------- | -------- | ------------ |
-| IDE `preToolUse` (Write/Edit) | Deny invalid reconstructable artifact candidates | Verified after live preToolUse Write smoke (2026-05-24) |
-| IDE `postToolUse` (Write/Edit) | Advisory validation through shared `validate_artifact.py` | Active |
-| CLI | Degraded; depends on workspace hook install and env propagation | Follows IDE smoke evidence only |
-
-Live preToolUse Write smoke passed on 2026-05-24 with invalid-block and valid-allow
-cases recorded in `.agentera/smoke-cursor-pretooluse-evidence.txt`. Conditional
-hard-gate claims for reconstructable IDE Write and Edit candidates are verified;
-release tagging and marketplace publication remain blocked pending broader release
-closeout.
-
-## Subagent dispatch
-
-IDE: managed descriptors under `.cursor/agents/` with `<!-- agentera: managed -->`
-ownership markers. Upgrade refreshes Agentera-owned targets and preserves unknown
-collisions.
-
-CLI: host-managed `cursor-agent` print mode; no separate TOML descriptor install.
-Eval coverage targets `cursor-agent` first.
-
-## Upgrade and doctor
-
-```bash
-uv run scripts/agentera upgrade --runtime cursor --dry-run
-uv run scripts/agentera doctor --runtime cursor
-```
-
-Upgrade copies managed hooks, agents, and plugin metadata into target projects
-with the same ownership protections used for OpenCode and Codex.
-
-Doctor reports helper access, hook presence, and managed agent alignment.
-
-## Eval
-
-```bash
-uv run scripts/eval_skills.py --runtime cursor-agent --skill hej --dry-run
-```
-
-Print mode uses `cursor-agent -p --output-format json --force`. Harnesses apply
-bounded timeouts because some CLI builds hang after completion.
-
-## Unsupported in v1
-
-- Cloud agents (no project hook or managed-agent guarantees)
-- Bare `hej` prompt rewrite routing
-- Session compaction injection beyond shared hook helpers
-- Separate cursor-agent hook install distinct from IDE workspace surfaces
-
-## Profilera session corpus (Section 22)
-
-Profilera mines five canonical record types from host session data. This section
-maps each record type to Cursor IDE local storage on disk.
-
-### Probe paths
-
-| Path | Purpose |
-| ---- | ------- |
-| `~/.cursor/projects/` | Root directory for workspace-scoped Cursor state |
-| `~/.cursor/projects/<project-slug>/agent-transcripts/<session-id>/*.jsonl` | Agent session transcripts (Composer / Agent) |
-| `~/.cursor/projects/<project-slug>/repo.json` | Workspace metadata (`id` UUID); slug mapping is primary for project scoping |
-| `~/.config/cursor/chats/<md5(project-path)>/<session-id>/store.db` | Cursor Agent CLI chat store (gap-fill when JSONL absent) |
-
-Override the projects root with `--cursor-projects-dir`, the CLI chats root with
-`--cursor-chats-dir`, or disable both Cursor runtimes with `--no-cursor` on
-`scripts/extract_corpus.py` and `agentera stats refresh`.
-
-Project slug convention: absolute project path segments joined with `-`, lowercased
-(for example `/home/user/git/agentera` → `home-user-git-agentera`). CLI workspace
-hashes use `md5(absolute-project-path)` hex (same string Cursor uses under
-`~/.config/cursor/chats/`). When `--project-root` is supplied, extraction prefers
-matching slugs and workspace hashes over unrelated stores.
-
-### Transcript JSONL shape
-
-Each line is a JSON object:
-
-```json
-{"role": "user", "message": {"content": [{"type": "text", "text": "..."}]}}
-{"role": "assistant", "message": {"content": [{"type": "text", "text": "..."}, {"type": "tool_use", "name": "grep", "input": {"pattern": "..."}}]}}
-```
-
-Roles are `user` or `assistant`. `message.content` is a list of blocks. Text blocks
-use `type: "text"`. Tool blocks use `type: "tool_use"` with `name` and `input`.
-
-### Cursor Agent CLI `store.db` shape
-
-Runtime id `cursor-agent` reads SQLite stores at
-`~/.config/cursor/chats/<workspace-hash>/<session-id>/store.db`. Each store has:
-
-| Table | Purpose |
-| ----- | ------- |
-| `blobs` | JSON message payloads keyed by content hash (`role`, `content`, optional tool blocks) |
-| `meta` | Session metadata (`agentId`, model, mode) |
-
-JSON blobs use `role` values such as `user`, `assistant`, and `tool`. User content is
-often a plain string; assistant content is a list that may include `text` and
-`tool-call` items (`toolName`, `args`). Sessions that already have IDE JSONL under
-`agent-transcripts/<same-session-id>/` are skipped (gap-fill only).
-
-### Portable record families
-
-| Family | Cursor source | Status |
-| ------ | ------------- | ------ |
-| Decision history | `history_prompt` from decision-rich user text blocks | Yes (local JSONL) |
-| Conversation exchanges | `conversation_turn` from user/assistant lines | Yes (local JSONL) |
-| Tool usage | `tool_call` from `tool_use` / `tool-call` blocks | Yes (bounded args) |
-| Instruction documents | Project `AGENTS.md` via shared `--project-root` scan | Yes (filesystem) |
-| Project config signals | Project manifests via shared `--project-root` scan | Yes (filesystem) |
-
-### Degradation and privacy
-
-Extraction is read-only and local-only. Runtime status uses the shared
-`runtime_statuses` vocabulary (`ok`, `missing`, `sparse`, `degraded`, `skipped`).
-Diagnostics report counts and bounded reasons only; raw transcript text must not
-appear in errors, smoke output, or test assertions.
-
-| Condition | Status | Reason |
-| --------- | ------ | ------ |
-| Store path disabled (`--no-cursor`) | `skipped` | `disabled` |
-| `~/.cursor/projects` or `~/.config/cursor/chats` absent | `missing` | `store_absent` |
-| No `*.jsonl` under `agent-transcripts` / no gap-fill `store.db` | `sparse` | `no_candidate_files` / `no_matching_records` |
-| Permission denied | `degraded` | `store_locked` |
-| Invalid JSONL lines | `degraded` | `schema_divergent` |
-| Candidates present but no normalized records | `sparse` | `no_matching_records` |
-
-### Gaps
-
-- Numeric or opaque project directory names (no slug) skip filesystem project-path
-  inference; `--project-root` mapping still scopes extraction when the slug matches.
-- Cloud agent sessions do not write local `agent-transcripts` in v1.
-- `cursor-agent` `store.db` sessions that already have IDE JSONL transcripts are skipped
-  to avoid duplicate corpus records; gap-fill covers chat-only CLI sessions.
-- Binary or non-JSON blobs in `store.db` degrade with bounded diagnostics and do not
-  leak transcript text.
-
-## Source of truth
-
-RuntimeAdapter records live in
-`references/adapters/runtime-adapter-registry.yaml`. Parity comparisons belong in
-`references/adapters/runtime-feature-parity.md`.