@gamaze/hicortex 0.17.6 → 0.18.0

package/dist/{context-cli.js → identity-cli.js}

@@ -1,54 +1,66 @@
 "use strict";
 /**
- * context-cli — `hicortex context show|edit`, the secondary/headless edit
- * surface for the standing context layer (spec 2026-07-12 §6). The Web UI
- * (`/context/ui`) is primary; this exists for boxes without a browser.
+ * identity-cli — `hicortex identity show|edit`, the secondary/headless edit
+ * surface for the standing identity layer (spec 2026-07-12 §6; renamed 0.18
+ * #264 from `context`). The Web UI (`/identity/ui`) is primary; this exists
+ * for boxes without a browser.
  *
- *   hicortex context show [name]   GET /context → print all sections, or one
- *   hicortex context edit <name>   GET section → $EDITOR → PUT if changed
+ *   hicortex identity show [name]   GET /identity → print all sections, or one
+ *   hicortex identity edit <name>   GET section → $EDITOR → PUT if changed
  *
- * URL/token resolution mirrors lessons-context.ts:44-49 (client mode →
+ * The legacy `hicortex context ...` command remains as a hidden alias so old
+ * scripts and muscle memory keep working (#264 backcompat).
+ *
+ * URL/token resolution mirrors learnings-identity.ts:44-49 (client mode →
  * config.serverUrl; server mode → http://127.0.0.1:<port>; token from
  * config.authToken) — explicitly NOT the hardcoded 127.0.0.1:8787 of
  * status.ts. Fails soft with a clear message + non-zero exit on any server
  * error, distinguishing a down server from an HTTP error (esp. 404 = server
  * too old / wrong endpoint), like the OC plugin's describeGetFailure.
+ *
+ * The CLI targets the new `/identity` endpoint. A 0.18+ server (this package)
+ * also keeps `/context` as an alias, so a new CLI against a not-yet-upgraded
+ * server falls back through that alias via describeFailure's 404 hint.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ContextCliError = void 0;
-exports.resolveContextTarget = resolveContextTarget;
+exports.runContextCommand = exports.getContext = exports.resolveContextTarget = exports.ContextCliError = exports.IdentityCliError = void 0;
+exports.resolveIdentityTarget = resolveIdentityTarget;
 exports.loadConfig = loadConfig;
 exports.sectionChanged = sectionChanged;
-exports.getContext = getContext;
+exports.getIdentity = getIdentity;
 exports.putSection = putSection;
 exports.formatAllSections = formatAllSections;
 exports.formatOneSection = formatOneSection;
 exports.runEdit = runEdit;
 exports.extractAgentFlag = extractAgentFlag;
-exports.runContextCommand = runContextCommand;
+exports.runIdentityCommand = runIdentityCommand;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
 const node_child_process_1 = require("node:child_process");
-const context_store_js_1 = require("./context-store.js");
+const identity_store_js_1 = require("./identity-store.js");
 const paths_js_1 = require("./paths.js");
 const DEFAULT_PORT = 8787;
 const REQUEST_TIMEOUT_MS = 5000;
 /** Thrown for any expected, user-facing failure. cli.ts prints .message + exits 1. */
-class ContextCliError extends Error {
+class IdentityCliError extends Error {
 }
-exports.ContextCliError = ContextCliError;
+exports.IdentityCliError = IdentityCliError;
+/** Backcompat alias (#264). */
+exports.ContextCliError = IdentityCliError;
 /**
  * Resolve the server URL + token from a parsed config object. Pure + exported
- * so it is unit-testable without a live config. Follows lessons-context.ts.
+ * so it is unit-testable without a live config. Follows learnings-identity.ts.
  */
-function resolveContextTarget(config) {
+function resolveIdentityTarget(config) {
     const baseUrl = config.mode === "client" && typeof config.serverUrl === "string"
         ? config.serverUrl.replace(/\/+$/, "")
         : `http://127.0.0.1:${config.port ?? DEFAULT_PORT}`;
     const authToken = typeof config.authToken === "string" ? config.authToken : undefined;
     return { baseUrl, authToken };
 }
+/** Backcompat alias (#264). */
+exports.resolveContextTarget = resolveIdentityTarget;
 /** Read ~/.hicortex/config.json (or $HICORTEX_HOME/config.json). Missing → {}. */
 function loadConfig() {
     try {
@@ -62,9 +74,9 @@ function loadConfig() {
 function sectionChanged(before, after) {
     return before !== after;
 }
-/** Append `?agent=<id>` to a /context URL when an agent scope is targeted. */
-function contextUrl(baseUrl, agent) {
-    return `${baseUrl}/context${agent ? `?agent=${encodeURIComponent(agent)}` : ""}`;
+/** Append `?agent=<id>` to a /identity URL when an agent scope is targeted. */
+function identityUrl(baseUrl, agent) {
+    return `${baseUrl}/identity${agent ? `?agent=${encodeURIComponent(agent)}` : ""}`;
 }
 function authHeaders(token) {
     return token ? { Authorization: `Bearer ${token}` } : {};
@@ -72,14 +84,15 @@ function authHeaders(token) {
 /**
  * Human-readable failure. status === null ⇒ the fetch itself threw (server
  * unreachable). 404 is called out because it means the server predates the
- * /context layer, not a network fault — mirrors index.ts describeGetFailure.
+ * /identity rename (it may still serve the legacy /context alias), not a
+ * network fault — mirrors index.ts describeGetFailure.
  */
 function describeFailure(status, bodyError) {
     const suffix = bodyError ? `: ${bodyError}` : "";
     if (status === null)
         return "server unreachable (connection refused or timed out)";
     if (status === 404)
-        return `HTTP 404 — /context not found; the server is likely too old (needs 0.12+)${suffix}`;
+        return `HTTP 404 — /identity not found; the server is likely too old (needs 0.18+; pre-0.18 serves /context)${suffix}`;
     if (status === 401)
         return `HTTP 401 — unauthorized; check authToken in config${suffix}`;
     return `server returned HTTP ${status}${suffix}`;
@@ -93,35 +106,37 @@ async function readBodyError(resp) {
         return undefined;
     }
 }
-/** GET /context. Throws ContextCliError with a clear message on any failure. */
-async function getContext(target, agent) {
+/** GET /identity. Throws IdentityCliError with a clear message on any failure. */
+async function getIdentity(target, agent) {
     let resp;
     try {
-        resp = await fetch(contextUrl(target.baseUrl, agent), {
+        resp = await fetch(identityUrl(target.baseUrl, agent), {
             headers: authHeaders(target.authToken),
             signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         });
     }
     catch {
-        throw new ContextCliError(`GET /context failed — ${describeFailure(null)}`);
+        throw new IdentityCliError(`GET /identity failed — ${describeFailure(null)}`);
     }
     if (!resp.ok) {
-        throw new ContextCliError(`GET /context failed — ${describeFailure(resp.status, await readBodyError(resp))}`);
+        throw new IdentityCliError(`GET /identity failed — ${describeFailure(resp.status, await readBodyError(resp))}`);
     }
     const data = (await resp.json());
     // Old-server echo guard: a pre-0.13 server ignores ?agent= and answers 200
     // with the GLOBAL set. Editing off that (then PUTting) would clobber shared
-    // context. Refuse unless the server echoes the agent it was asked for.
+    // identity. Refuse unless the server echoes the agent it was asked for.
     if (agent && data.agent !== agent) {
-        throw new ContextCliError(`server did not echo agent '${agent}' — it likely predates per-agent context (needs 0.13+)`);
+        throw new IdentityCliError(`server did not echo agent '${agent}' — it likely predates per-agent identity (needs 0.13+)`);
     }
     return data;
 }
-/** PUT one section. Throws ContextCliError with a clear message on any failure. */
+/** Backcompat alias (#264). */
+exports.getContext = getIdentity;
+/** PUT one section. Throws IdentityCliError with a clear message on any failure. */
 async function putSection(target, name, content, agent) {
     let resp;
     try {
-        resp = await fetch(contextUrl(target.baseUrl, agent), {
+        resp = await fetch(identityUrl(target.baseUrl, agent), {
             method: "PUT",
             headers: { "Content-Type": "application/json", ...authHeaders(target.authToken) },
             body: JSON.stringify({ sections: { [name]: content } }),
@@ -129,10 +144,10 @@ async function putSection(target, name, content, agent) {
         });
     }
     catch {
-        throw new ContextCliError(`PUT /context failed — ${describeFailure(null)}`);
+        throw new IdentityCliError(`PUT /identity failed — ${describeFailure(null)}`);
     }
     if (!resp.ok) {
-        throw new ContextCliError(`PUT /context failed — ${describeFailure(resp.status, await readBodyError(resp))}`);
+        throw new IdentityCliError(`PUT /identity failed — ${describeFailure(resp.status, await readBodyError(resp))}`);
     }
     // Old-server echo guard on the WRITE too: a pre-0.13 server silently accepts
     // the PUT as a GLOBAL write and returns 200 without echoing `agent`. Treat a
@@ -141,8 +156,8 @@ async function putSection(target, name, content, agent) {
     if (agent) {
         const body = (await resp.json().catch(() => ({})));
         if (body.agent !== agent) {
-            throw new ContextCliError(`PUT /context?agent=${agent} — server did not echo the agent; it likely predates per-agent ` +
-                `context (needs 0.13+). It may have written to the GLOBAL scope — verify the server version.`);
+            throw new IdentityCliError(`PUT /identity?agent=${agent} — server did not echo the agent; it likely predates per-agent ` +
+                `identity (needs 0.13+). It may have written to the GLOBAL scope — verify the server version.`);
         }
     }
 }
@@ -154,7 +169,7 @@ function formatAllSections(data) {
     const names = Object.keys(data.sections);
     const parts = [];
     if (names.length === 0) {
-        parts.push("(no context sections)");
+        parts.push("(no identity sections)");
     }
     else {
         for (const name of names) {
@@ -202,7 +217,7 @@ const defaultSpawn = (file) => {
 // Commands
 // ---------------------------------------------------------------------------
 async function runShow(name, agent) {
-    const data = await getContext(resolveContextTarget(loadConfig()), agent);
+    const data = await getIdentity(resolveIdentityTarget(loadConfig()), agent);
     if (name) {
         const body = formatOneSection(data, name);
         if (body === null) {
@@ -221,19 +236,19 @@ async function runShow(name, agent) {
  * always cleaned up. `spawn` is injectable for tests.
  */
 async function runEdit(name, spawn = defaultSpawn, agent) {
-    if (!(0, context_store_js_1.isValidSectionName)(name)) {
-        throw new ContextCliError(`Invalid section name '${name}'. Must match ^[a-z0-9][a-z0-9_-]*$ (max ${context_store_js_1.SECTION_NAME_MAX} chars).`);
+    if (!(0, identity_store_js_1.isValidSectionName)(name)) {
+        throw new IdentityCliError(`Invalid section name '${name}'. Must match ^[a-z0-9][a-z0-9_-]*$ (max ${identity_store_js_1.SECTION_NAME_MAX} chars).`);
     }
-    const target = resolveContextTarget(loadConfig());
-    const data = await getContext(target, agent);
+    const target = resolveIdentityTarget(loadConfig());
+    const data = await getIdentity(target, agent);
     const before = data.sections[name] ?? "";
-    const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "hicortex-ctx-"));
+    const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "hicortex-id-"));
     const file = (0, node_path_1.join)(dir, `${name}.md`);
     try {
         (0, node_fs_1.writeFileSync)(file, before, "utf-8");
         const ran = spawn(file);
         if (!ran) {
-            throw new ContextCliError("No editor available. Set $EDITOR, or install nano or vi.");
+            throw new IdentityCliError("No editor available. Set $EDITOR, or install nano or vi.");
         }
         const after = (0, node_fs_1.readFileSync)(file, "utf-8");
         if (!sectionChanged(before, after)) {
@@ -261,7 +276,7 @@ function extractAgentFlag(args) {
             // A missing value (end of args) or the next token being another flag is a
             // typo — never let it silently fall through to the global scope.
             if (val === undefined || val.startsWith("-")) {
-                throw new ContextCliError("--agent requires a value, e.g. --agent alice");
+                throw new IdentityCliError("--agent requires a value, e.g. --agent alice");
             }
             agent = val;
             i++;
@@ -271,12 +286,13 @@ function extractAgentFlag(args) {
     }
     return { agent, rest };
 }
-/** Dispatch for `hicortex context <sub>`. Throws ContextCliError on bad usage/failure. */
-async function runContextCommand(args) {
+/** Dispatch for `hicortex identity <sub>` (and the hidden `context` alias).
+ *  Throws IdentityCliError on bad usage/failure. */
+async function runIdentityCommand(args) {
     const { agent, rest } = extractAgentFlag(args);
     // Fast-fail on a bad agent id before any HTTP call (the server enforces too).
-    if (agent !== undefined && !(0, context_store_js_1.isValidAgentId)(agent)) {
-        throw new ContextCliError(`Invalid agent id '${agent}'. Must match ^[a-z0-9][a-z0-9_-]*$ (max ${context_store_js_1.SECTION_NAME_MAX} chars).`);
+    if (agent !== undefined && !(0, identity_store_js_1.isValidAgentId)(agent)) {
+        throw new IdentityCliError(`Invalid agent id '${agent}'. Must match ^[a-z0-9][a-z0-9_-]*$ (max ${identity_store_js_1.SECTION_NAME_MAX} chars).`);
     }
     const sub = rest[0];
     switch (sub) {
@@ -285,10 +301,12 @@ async function runContextCommand(args) {
             return;
         case "edit":
             if (!rest[1])
-                throw new ContextCliError("Usage: hicortex context edit <name> [--agent <id>]");
+                throw new IdentityCliError("Usage: hicortex identity edit <name> [--agent <id>]");
             await runEdit(rest[1], undefined, agent);
             return;
         default:
-            throw new ContextCliError("Usage: hicortex context <show [name] | edit <name>> [--agent <id>]");
+            throw new IdentityCliError("Usage: hicortex identity <show [name] | edit <name>> [--agent <id>]");
     }
 }
+/** Backcompat alias (#264). */
+exports.runContextCommand = runIdentityCommand;

package/dist/{context-store.d.ts → identity-store.d.ts}

@@ -1,15 +1,16 @@
 /**
- * Context layer (L2) — file-backed storage (0.12.0, spec 2026-07-12).
+ * Identity layer — file-backed storage (formerly "Context Layer" / L2; 0.12.0,
+ * spec 2026-07-12; renamed 0.18 #264).
  *
- * The context layer is hand-edited Markdown ("who you are + how to work") stored
- * as plain files in `<hicortex-home>/context/*.md` — one file per section, one
+ * The identity layer is hand-edited Markdown ("who you are + how to work") stored
+ * as plain files in `<hicortex-home>/identity/*.md` — one file per section, one
  * Web UI tab. It lives OUTSIDE the memories table: never distilled, scored,
  * decayed, or pruned. As plain files this guarantee is structural — no code in
  * consolidate.ts / distiller.ts references this directory.
  *
  * This module is pure file-layer logic (no express) so it is unit-testable and
  * reusable by the CLI. The daemon resolves `<hicortex-home>` exactly as it
- * resolves the DB dir (dirname of the resolved DB path) and passes the context
+ * resolves the DB dir (dirname of the resolved DB path) and passes the identity
  * dir in — nothing here hardcodes `~`.
  *
  * Security contract (spec §1): client-supplied section names are NEVER joined
@@ -17,6 +18,14 @@
  * itself appends `.md`. Reads skip symlinks (lstat, not stat). Writes validate
  * ALL names before touching the disk (atomic request semantics), go via
  * temp-file-then-rename, and keep a one-generation `<name>.md.bak` undo.
+ *
+ * Backcompat (#264): the pre-rename directory was `<hicortex-home>/context/`.
+ * `migrateIdentityDir` renames it to `identity/` on the next init/nightly run
+ * when the old dir exists and the new does not. When BOTH exist (partial
+ * migration, a disk-full renameSync failure, or an operator re-creating
+ * `context/`), reads ADDITIVELY MERGE: per-section `identity/` wins, and
+ * legacy-only sections are included so nothing is lost — at both the global
+ * and the per-agent (`agents/<id>/`) level.
  */
 /** A valid section name: lowercase alnum start, then alnum / `_` / `-`. */
 export declare const SECTION_NAME_RE: RegExp;
@@ -36,11 +45,11 @@ export declare class InvalidSectionNameError extends Error {
 }
 /** Resolution mode for a given agent id (spec §3). */
 export type AgentMode = "override" | "global" | "off";
-/** Reserved subdir under <context>/ holding per-agent sections. NOT a section. */
+/** Reserved subdir under <identity>/ holding per-agent sections. NOT a section. */
 export declare const AGENTS_DIR = "agents";
 /**
  * Agent ids share the section-name allowlist: they are joined into a filesystem
- * path (`context/agents/<id>`), so this is the same security contract, not just
+ * path (`identity/agents/<id>`), so this is the same security contract, not just
  * hygiene.
  */
 export declare const isValidAgentId: typeof isValidSectionName;
@@ -72,21 +81,41 @@ export interface AgentIdentity {
  *  - absent, or empty/whitespace-only → null id, "unset". Empty string == unset
  *    everywhere (this is the value `init --agent-name ""` writes-then-clears to
  *    opt back out): CC's default is NO `?agent=`, so all CC boxes for one user
- *    share the global context — one user = one identity across machines.
+ *    share the global identity — one user = one identity across machines.
  * There is NO hostname fallback: a hostname-derived default would silently give
- * every machine its own context, the opposite of the shared-identity default.
+ * every machine its own identity, the opposite of the shared-identity default.
  */
 export declare function resolveAgentIdentity(config: Record<string, unknown>): AgentIdentity;
 /**
- * Normalize the raw `contextAgents` config value into a map of valid agent id →
+ * Normalize the raw `identityAgents` config value into a map of valid agent id →
  * mode. An entry is kept only when its key passes isValidAgentId AND its value
  * is one of the three modes; everything else is dropped and its key collected
- * for a one-time boot warning (mirrors resolveContextClients).
+ * for a one-time boot warning (mirrors resolveIdentityClients).
+ *
+ * Backcompat (#264): the pre-rename key was `contextAgents`. Callers that want
+ * to honour it should pass the already-resolved value here (see
+ * `resolveIdentityConfig` in mcp-server.ts which reads new + old).
  */
-export declare function resolveContextAgents(raw: unknown): {
+export declare function resolveIdentityAgents(raw: unknown): {
     agents: Record<string, AgentMode>;
     dropped: string[];
 };
+/**
+ * Rename `<home>/context/` → `<home>/identity/` when the legacy dir exists and
+ * the new dir does not. Idempotent + safe: when both exist (a partial
+ * migration, or the operator created both) NOTHING is renamed — the caller
+ * falls back to a legacy read instead. Returns a description of what happened
+ * for a one-time boot log.
+ *
+ * Called from init and nightly so the migration lands on the next run of either
+ * command an existing install hits.
+ */
+export declare function migrateIdentityDir(home: string): {
+    renamed: boolean;
+    from: string;
+    to: string;
+    reason?: string;
+};
 export interface ReadResult {
     sections: Record<string, string>;
     /** ISO timestamp of the latest included file's mtime, or null when none. */
@@ -95,7 +124,7 @@ export interface ReadResult {
     mtimes: Record<string, number>;
 }
 /**
- * Enumerate the context dir and return the served sections. Only regular files
+ * Enumerate the identity dir and return the served sections. Only regular files
  * whose basename (sans `.md`) passes the allowlist are included; symlinks are
  * skipped (lstat). `<name>.md.bak` and temp files never match the `*.md` filter.
  *
@@ -103,6 +132,14 @@ export interface ReadResult {
  * null }` and NEVER creates the dir or throws.
  */
 export declare function readSections(dir: string): ReadResult;
+/**
+ * Read the identity dir, additively merging the legacy `context/` sibling so
+ * nothing is lost when both dirs exist (post-#264 safety net for a partial/no
+ * migration: a disk-full renameSync failure, or an operator re-creating
+ * `context/`). Per-section, `identity/` wins; legacy-only sections are included
+ * (union). Pure function over the two dirs — used by the GET handler.
+ */
+export declare function readSectionsWithFallback(identityDir: string): ReadResult;
 /**
  * Partial upsert of the named sections. Contract (spec §1):
  *  - Validate ALL names first; any invalid → throw InvalidSectionNameError and
@@ -134,29 +171,55 @@ export declare function writeSections(dir: string, sections: Record<string, stri
 /** Total UTF-8 byte size of all sections (used for the >16 KB warn). */
 export declare function totalBytes(sections: Record<string, string>): number;
 /** Warn threshold: this layer bypasses token budgeting and injects every session. */
+export declare const IDENTITY_SIZE_WARN_BYTES = 16384;
+/** Backcompat alias for the pre-rename name (#264). */
 export declare const CONTEXT_SIZE_WARN_BYTES = 16384;
-/** Harness names that may inject the context layer. */
+/** Harness names that may inject the identity layer. */
+export declare const KNOWN_IDENTITY_CLIENTS: readonly ["cc", "hermes", "oc"];
+/** Backcompat alias for the pre-rename name (#264). */
 export declare const KNOWN_CONTEXT_CLIENTS: readonly ["cc", "hermes", "oc"];
-export interface ResolvedContextClients {
+export interface ResolvedIdentityClients {
     /** The resolved, de-duped list of known client names. */
     clients: string[];
     /** Unknown names dropped from an array value (for a one-time boot warning). */
     dropped: string[];
 }
+/** Backcompat alias for the pre-rename name (#264). */
+export type ResolvedContextClients = ResolvedIdentityClients;
 /**
- * Normalize the raw `contextClients` config value (spec §2):
+ * Normalize the raw `identityClients` config value (spec §2):
  *  - `"all"` (any case)      → ["cc","hermes","oc"]
  *  - array                   → lowercase, keep known names (de-duped), collect dropped unknowns
  *  - missing / non-array-non-"all" → default ["cc"]
- * The resolved list is echoed by GET /context as `clients` so each harness's
+ * The resolved list is echoed by GET /identity as `clients` so each harness's
  * hook can self-gate without its own config.
  */
-export declare function resolveContextClients(raw: unknown): ResolvedContextClients;
+export declare function resolveIdentityClients(raw: unknown): ResolvedIdentityClients;
+/**
+ * Read the identity-clients config value from a raw config object, honouring
+ * the new key (`identityClients`) and falling back to the legacy
+ * `contextClients` (#264) with a one-time deprecation signal. Returns the
+ * resolved clients, dropped unknowns, and whether the value came from the
+ * legacy key.
+ */
+export declare function resolveIdentityClientsConfig(config: Record<string, unknown> | undefined | null): ResolvedIdentityClients & {
+    legacy: boolean;
+};
+/**
+ * Read the identity-agents config value from a raw config object, honouring
+ * the new key (`identityAgents`) and falling back to the legacy
+ * `contextAgents` (#264) with a one-time deprecation signal.
+ */
+export declare function resolveIdentityAgentsConfig(config: Record<string, unknown> | undefined | null): {
+    agents: Record<string, AgentMode>;
+    dropped: string[];
+    legacy: boolean;
+};
 /**
- * Classify the on-disk state of `context/agents/<id>`, hardened against a
+ * Classify the on-disk state of `identity/agents/<id>`, hardened against a
  * symlink planted at EITHER the `agents` ROOT or the `<id>` leaf — lstat/readdir
  * follow a symlinked intermediate path component, so checking only the leaf
- * would let a symlinked root escape the context root entirely. BOTH must be
+ * would let a symlinked root escape the identity root entirely. BOTH must be
  * real, non-symlink directories.
  *  - "absent" — the root or the leaf does not exist (fresh install / no dir for
  *    this agent). A normal, safe "no agent sections" case.
@@ -167,24 +230,24 @@ export declare function resolveContextClients(raw: unknown): ResolvedContextClie
  * rethrow (a permissions fault must never masquerade as "empty", matching
  * readSections). The single source of truth for the four call sites below.
  */
-export declare function agentDirState(contextDir: string, agentId: string): "absent" | "real" | "unsafe";
+export declare function agentDirState(identityDir: string, agentId: string): "absent" | "real" | "unsafe";
 /**
  * Resolve the mode for a request `?agent=<id>` (spec §3):
  *  1. config entry present → that mode;
- *  2. else `context/agents/<id>/` present as a REAL directory (root + leaf both
+ *  2. else `identity/agents/<id>/` present as a REAL directory (root + leaf both
  *     real, non-symlink) → "override" (dropping in a dir is intent, no config);
  *  3. else → "global".
  * A symlinked/non-dir root or leaf never counts as "present" (agentDirState).
  */
-export declare function resolveAgentMode(contextDir: string, agentId: string, contextAgents: Record<string, AgentMode>): AgentMode;
+export declare function resolveAgentMode(identityDir: string, agentId: string, identityAgents: Record<string, AgentMode>): AgentMode;
 /**
  * Enumerate the agents the UI selector should offer: the union of allowlisted
- * REAL directories under `context/agents/` and every configured `contextAgents`
+ * REAL directories under `identity/agents/` and every configured `identityAgents`
  * key, each mapped to its resolved mode (config wins over presence). A missing
  * agents dir (fresh install) yields the config keys only; a symlinked/non-dir
  * agents root is treated as "no dirs" (config keys only).
  */
-export declare function listAgents(contextDir: string, contextAgents: Record<string, AgentMode>): Record<string, AgentMode>;
+export declare function listAgents(identityDir: string, identityAgents: Record<string, AgentMode>): Record<string, AgentMode>;
 export interface ResolvedRead {
     sections: Record<string, string>;
     updatedAt: string | null;
@@ -202,7 +265,7 @@ export interface ResolvedRead {
  * reading (A1): a symlinked or non-directory `agents/<id>` contributes NO agent
  * sections regardless of how override was selected (config or presence).
  */
-export declare function readResolvedSections(contextDir: string, agentId: string | null, contextAgents: Record<string, AgentMode>): ResolvedRead;
+export declare function readResolvedSections(identityDir: string, agentId: string | null, identityAgents: Record<string, AgentMode>): ResolvedRead;
 export interface HandlerResult {
     status: number;
     body: unknown;
@@ -210,17 +273,17 @@ export interface HandlerResult {
     warn?: string;
 }
 /**
- * GET /context. Stale-client tripwire first: recall moved to /recent, so
+ * GET /identity. Stale-client tripwire first: recall moved to /recent, so
  * project/limit/privacy on this route mean a legacy recall caller — return a
- * loud 400 rather than silently degrading to an empty context-layer response.
- * (A bare GET /context with no params is the legitimate context-layer read and
+ * loud 400 rather than silently degrading to an empty identity-layer response.
+ * (A bare GET /identity with no params is the legitimate identity-layer read and
  * is served normally — the two are indistinguishable at the wire, so a
  * paramless legacy caller is covered by the migration docs, not this guard.)
  */
-export declare function handleContextGet(contextDir: string, clients: string[], query: Record<string, unknown>, contextAgents?: Record<string, AgentMode>): HandlerResult;
+export declare function handleIdentityGet(identityDir: string, clients: string[], query: Record<string, unknown>, identityAgents?: Record<string, AgentMode>): HandlerResult;
 /**
- * PUT /context. Validates the body shape and section content types, then
+ * PUT /identity. Validates the body shape and section content types, then
  * delegates to writeSections (which owns the name allowlist + atomicity +
  * symlink safety). Throws are left to the adapter to turn into a 500.
  */
-export declare function handleContextPut(contextDir: string, body: unknown, query?: Record<string, unknown>, contextAgents?: Record<string, AgentMode>): HandlerResult;
+export declare function handleIdentityPut(identityDir: string, body: unknown, query?: Record<string, unknown>, identityAgents?: Record<string, AgentMode>): HandlerResult;