total-recall-brain 3.6.9 → 3.6.11

package/bin/total-recall.mjs

@@ -79,6 +79,7 @@ const COMMANDS = {
   skill:    'skill.mjs',
   help:     'help.mjs',
   collab:   'collab.mjs',
+  command:  'command.mjs',
 };
 function printHelp() {
   console.log(`
@@ -128,6 +129,7 @@ function printHelp() {
     uninstall           Completely uninstall all services, launchd agents, VFS, and shims
     help <topic>        Interactive offline documentation, SSSS reference, and system help
     collab              Start Express/WebSockets backend & React collab sandbox dev server
+    command <create|read|update|remove|list>  Manage custom project-local CLI commands
 
 
 
@@ -166,8 +168,29 @@ async function main() {
   if (!handlerFile) {
     // Check if it is a dynamic integration command configured in the VFS
     try {
-      const { agentDir } = await import('../src/core/config.mjs');
+      const { agentDir, resolveBrainLayer } = await import('../src/core/config.mjs');
       const fs = await import('node:fs');
+      
+      // Check for custom project-level commands first
+      let projectAgentDir = null;
+      try {
+        const pBrain = resolveBrainLayer('project');
+        projectAgentDir = pBrain.agentDir;
+      } catch (e) { /* ignore */ }
+      
+      if (projectAgentDir) {
+        const customCmdPath = path.join(projectAgentDir, 'commands', `${command}.mjs`);
+        if (fs.existsSync(customCmdPath)) {
+          const handler = await import(customCmdPath);
+          if (handler.run) {
+            await handler.run(process.argv);
+          } else {
+            await handler.default(process.argv.slice(3));
+          }
+          process.exit(0);
+        }
+      }
+
       const integrationPath = path.join(agentDir, 'skills', 'total-recall', 'integrations', `${command}.md`);
       
       if (fs.existsSync(integrationPath)) {

package/frontend/src/pages/LoginPage.tsx

@@ -142,6 +142,7 @@ export default function LoginPage({ onAuthenticated }: Props) {
 
         {/* Form */}
         <form onSubmit={handleSubmit} style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+          <input type="text" name="username" autoComplete="username" style={{ display: "none" }} />
           <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
             <label htmlFor="login-password" style={{ fontSize: 12, fontWeight: 600, color: "var(--text-secondary)", textTransform: "uppercase", letterSpacing: "0.05em" }}>
               {(needsReset || isFirstTime) ? "New Password" : "Password"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.6.9",
+  "version": "3.6.11",
   "description": "Sovereign AI system — database-free, SSSS-powered personal intelligence engine deployable to any POSIX host.",
   "type": "module",
   "bin": {

package/scaffold/.agent/skills/total-recall/SKILL.md

@@ -54,7 +54,24 @@ Total Recall operates **entirely database-free**. The local filesystem is the so
 ### 2. Precise Tool & API Selection Heuristics
 When interacting with the system, choose your interfaces based on the following:
 *   **Local Skills**: Use local skill packages (located in `.agent/skills/`) for complex workspace tasks, testing, and formatting. If a local skill has custom helper scripts, ALWAYS invoke them via your shell command tool instead of running raw standard commands.
-*   **Total Recall Brain (MANDATORY)**: For all semantic searches, memory retrieval, memory writes, and derived index recompilation, **use either the local CLI suite (`npx total-recall`) or shell `curl` commands** targeting the REST API endpoints documented below.
+*   **Total Recall CLI (PRIMARY — use this)**: For all memory operations — saving, recalling, forgetting, and compiling — use the `npx total-recall` CLI commands. This is the correct and preferred interface.
+    ```bash
+    npx total-recall recall "your query here" --top-k 5
+    npx total-recall remember invariant "rule text" --importance 5 --priority absolute
+    npx total-recall remember fact "fact text" --project
+    npx total-recall forget <slug>
+    npx total-recall compile
+    ```
+*   **Custom Local Commands**: The Total Recall CLI supports managing project-specific CLI commands dynamically. Use the `command` subcommand to manage these.
+    ```bash
+    npx total-recall command create hello "console.log('Hello from the brain!');"
+    npx total-recall command list
+    npx total-recall command read hello
+    npx total-recall command update hello "console.log('Updated hello command');"
+    npx total-recall command remove hello
+    ```
+    Custom commands are auto-generated and stored in the workspace at `.agent/commands/<name>.mjs`.
+*   **REST API via curl (SECONDARY — fallback only)**: Use raw `curl` commands to the REST API endpoints only when the CLI is unavailable or for advanced programmatic use cases not covered by the CLI.
 
 ### 3. Non-Destructive Code Modifications
 When modifying existing rule surfaces or IDE shims (such as `.cursorrules`, `CLAUDE.md`, `GEMINI.md`, etc.), **NEVER** overwrite the developer's custom pre-existing rules. Instead, write compiled absolute invariants inside the managed comment block:

package/scaffold/.agent/skills/total-recall/skills/ssss/SKILL.md

@@ -1,46 +1,196 @@
 ---
 type: skill
 name: ssss
-description: "Use this skill to inspect, validate, write, and manage SSSS structured semantic memory nodes and VFS specifications. Do NOT use for raw non-schema memory files."
+description: "Use this skill to inspect, validate, write, and manage SSSS primitives, memory nodes, operation envelopes, scope overlays, projections, and VFS specifications in the Total Recall reference kernel. MANDATORY: Read this file before editing SSSS files or code."
 schema_version: 2
 ---
 
 # SSSS — Structured Semantic Syntax System Manager
 
-Structured Semantic Syntax System (ssss) is the core operational substrate of the Total Recall Virtual File System (VFS). This skill guides agents in inspecting, reading, and constructing SSSS-compliant memory nodes, conflict models, and derived indices.
+SSSS is the Markdown-first state contract for Total Recall and compatible VFS
+hosts. Use this skill when touching memory nodes, skills, assistants, workflows,
+models, conversations, runs, projection metadata, operation envelopes, or SSSS
+schema/reference files.
 
-## Spec Version
+## Ground Truth
 
-Current specification: **v0.2 — Draft** (see `references/ssss-spec.md`)
+The vendor-neutral contract is `references/ssss-spec.md`. If this skill conflicts
+with the spec, correct this skill unless the implementation has intentionally
+advanced beyond the vendored spec and the difference is documented here.
 
-### v0.2 Changes (2026-05-30)
-- Expanded `modality` enum: `must|must_not|should|should_not|descriptive|preference`
-- Expanded `priority` enum: `absolute|high|normal|low` (OPTIONAL, defaults to `normal`)
-- Added §10.1: Projection Manifest requirement with vault-hash staleness detection
-- Added §11.3: Single canonical embedding implementation (no dual systems)
+Current local implementation entry points:
 
-## Core Directives
+- `src/core/schema.mjs` — implemented SSSS primitive registry (`SSSS_SCHEMAS`).
+- `src/core/operation-validator.mjs` — §6 operation pipeline.
+- `src/core/validated-write.mjs` — memory write adapter for the operation
+  pipeline.
+- `src/core/total-recall-memory-validator.mjs` — schema v2 memory validator.
+- `src/core/vault-cache.mjs` — cached vault reads and watcher invalidation.
+- `src/core/vector-store.mjs` and `src/core/semantic-index.mjs` — canonical
+  search/index path.
 
-1. **Schema Integrity:** Every SSSS node must strictly adhere to the frontmatter schema definitions (Modality, Category, Sentiment).
-2. **Zero-Database Persistence:** Do not look for Postgres or SQLite. Everything lives as a git-versioned Markdown file.
-3. **Decay and Drift Monitoring:** Use decay indicators to manage node half-lives dynamically in background ticks.
-4. **Cached Reads:** All vault reads MUST go through `vault-cache.mjs` (`getNodes()`) — never call `loadNodes()` directly. The cache supports multi-directory (global + project) with per-directory `fs.watch` invalidation.
-5. **Operation Contract:** All agent-generated mutations MUST flow through `processOperation()` (§6). Direct `writeNode()` calls bypass validation, idempotency, authorization, lease protection, and audit logging.
+## Current Contract
 
-## Progressive Memory Disclosure
+All agent-generated mutations must flow through the SSSS operation pipeline:
 
-Memory flows through a 3-tier progressive hierarchy:
-* **Tier 1 (Hot):** INSTRUCTIONS.md shims (Invariants only).
-* **Tier 2 (Warm):** SKILL.md injects (Category-routed warm capsules).
-* **Tier 3 (Cold):** Full memory vault (Search index files on demand).
+```text
+processOperation(envelope, vaultRoot, options)
+  -> envelope validation
+  -> idempotency check
+  -> authorization
+  -> lease validation
+  -> deterministic schema validation
+  -> atomic commit
+  -> audit event
+```
 
-## Performance Invariants
+Use `writeNodeValidated()` for Total Recall memory writes. Do not call raw
+`writeNode()` or write files directly when an agent is mutating an SSSS vault.
 
-* `vault-cache.mjs` is the **single import point** for all node reads. The cache uses `fs.watch` auto-invalidation and supports multiple vault directories simultaneously.
-* `walkMd()` uses `{ withFileTypes: true }` to eliminate per-file `stat()` syscalls.
-* `deleteNode()` scans category directories directly — O(categories) not O(nodes).
-* Surface recompilation (`triggerMutation()`) is debounced with a 2-second quiet period for batch writes.
+Total Recall currently implements these envelope types in
+`processOperation()`:
+
+- `operation` — full file create/replace.
+- `patch` — partial frontmatter/body merge.
+- `event` — append-only JSON event payload.
+
+The UltraChat host also models a `delete` envelope. Do not claim or use `delete`
+inside the Total Recall kernel until `src/core/schema.mjs` and
+`src/core/operation-validator.mjs` implement and test it. For memory removal, use
+the CLI/API forget/archive flow.
+
+Use `dry_run: true` for preflight validation when constructing writes from model
+output.
+
+## Canonical State
+
+The vault is source-of-truth. Derived files, embeddings, search indexes,
+instruction shims, UI caches, and projection manifests are disposable and must be
+rebuildable from Markdown vault state plus append-only events.
+
+Total Recall is database-free. Do not look for Postgres or SQLite as the record of
+truth. The internal vector store is a derived index, not canonical state.
+
+## Scope Layers
+
+Total Recall memory has layered vault scope:
+
+- `global` — machine/user-level brain shared across registered projects.
+- `project` — repository-local brain and session context.
+
+Host applications can add product runtime scopes such as `system`, `account`, and
+`workspace`. The UltraChat implementation proved the rule that shared system
+skills must be inherited through an overlay, not copied into every workspace.
+When authoring portable SSSS guidance, preserve this separation:
+
+- system/platform primitives are hidden shared defaults;
+- account-local primitives must not leak into workspace runtimes unless forked or
+  explicitly installed;
+- workspace primitives can shadow shared system defaults;
+- legacy copied system artifacts should be treated as derived cleanup targets only
+  when metadata proves they are seeded copies.
+
+Do not flatten these layers into one directory or one effective identity in docs,
+validators, or examples.
+
+## Primitive Registry
+
+`src/core/schema.mjs` is the implementation registry. `references/ssss-spec.md`
+is the vendor-neutral baseline. When adding or changing a primitive:
+
+1. Update `SSSS_SCHEMAS` and the relevant Zod schema.
+2. Update the spec or this skill if the primitive is standard or host-specific
+   respectively.
+3. Add/adjust fixtures or tests for the required fields and invalid cases.
+4. Confirm projection behavior is declared as source, projection, or external
+   state.
+
+The current implementation includes the core spec primitives plus host/product
+extensions such as `personalization_profile`, `account_assistant`,
+`account_memory`, `account_workflow`, `workspace_transfer`, CRM/CMS/commerce
+types, telephony types, and workspace/package types. Treat those as implemented
+host extensions unless the spec explicitly standardizes them.
+
+## Memory Nodes
+
+Memory files under `.agent/memory-vault/**` are `type: memory` and must satisfy
+SSSS schema v2. Required schema v2 knowledge-graph fields are:
+
+- `confidence`
+- `importance`
+- `modality`
+- `subject`
+- `predicate`
+- `object`
+- `sentiment_polarity`
+- `sentiment_target`
+
+Invariants additionally use `priority: absolute` and `immutable: true`.
+
+Memory validation is owned by `TotalRecallMemoryValidator`, not by generic loose
+frontmatter checks. No memory path may be committed with zero validation.
+
+## Reads And Writes
+
+- Use `vault-cache.mjs` `getNodes()` for vault reads. Do not call `loadNodes()`
+  directly in new code.
+- Use `writeNodeValidated()` or `processOperation()` for writes.
+- Invalidate the vault cache after successful writes.
+- Keep append-type documents append-only. `conversation` and `run` may append
+  body records but must not rewrite prior records.
+- Events are immutable. Do not update or delete event records.
+- Leases must be time-bound, actor-owned, operation-linked, and recoverable.
+
+## Projections And Indexes
+
+Projection manifests must mark derived artifacts as disposable and record enough
+provenance to detect drift. A projection must have a rebuild path from vault state
+and events or be documented as external non-projection state.
+
+The canonical search/index stack is the Total Recall semantic index/vector store.
+Do not introduce a second embedding or indexing path for SSSS memory unless the
+spec and tests are updated together.
+
+## Validation
+
+Validate an individual SSSS Markdown file with:
+
+```bash
+node .agent/skills/ssss/scripts/validate-schema.mjs <path-to-node.md>
+```
+
+Run focused kernel tests after changing the operation contract, schema registry,
+validator, or vault cache:
+
+```bash
+npx vitest run \
+  src/core/schema.spec.mjs \
+  src/core/operation-validator.spec.mjs \
+  src/core/total-recall-memory-validator.spec.mjs \
+  src/core/vault-cache.spec.mjs
+```
+
+## Do Not
+
+- Do not write agent mutations directly to vault files.
+- Do not make derived indexes or projections canonical.
+- Do not bypass deterministic validation for model-generated changes.
+- Do not collapse `global`/`project` or `system`/`account`/`workspace` scope
+  boundaries.
+- Do not represent copied seeded skills as canonical system primitives.
+- Do not claim Total Recall supports `delete` envelopes until the implementation
+  supports them.
+- Do not add host-specific required fields to the vendor-neutral spec unless they
+  are being standardized.
 
 ## References
 
-* Core SSSS specification: `references/ssss-spec.md`
+| For | Read |
+| --- | --- |
+| SSSS standard | `references/ssss-spec.md` |
+| Implemented schemas | `src/core/schema.mjs` |
+| Operation pipeline | `src/core/operation-validator.mjs` |
+| Validated memory writes | `src/core/validated-write.mjs` |
+| Memory validator | `src/core/total-recall-memory-validator.mjs` |
+| Vault cache | `src/core/vault-cache.mjs` |
+| Total Recall SSSS v2 reference | `.agent/skills/total-recall/references/ssss-reference.md` |

package/scaffold/.agent/skills/total-recall/skills/ssss/references/CHANGELOG.md

@@ -0,0 +1,9 @@
+# SSSS Changelog
+
+## [v0.2.0] - 2026-06
+- **Changed**: Stripped product-specific primitives (`meeting`, `event`, `crm`, etc.) from the core specification to enforce vendor-neutrality. Product primitives must now live strictly in host-level registries.
+- **Added**: Upgraded Total Recall, UltraChat, and MUSE to v0.2.0 alignment.
+
+## [v0.1.0] - 2026-05
+- Initial Draft Specification.
+- Defined VFS primitives, Operation Contract, and Append-Only Event Graph.

package/scaffold/.agent/skills/total-recall/skills/ssss/scripts/validate-schema.mjs

@@ -1,54 +1,232 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import matter from 'gray-matter';
 
+const APPEND_TYPES = new Set(['conversation', 'run']);
+const CONTRACT_ONLY_TYPES = new Set(['operation', 'patch', 'lease']);
+const V2_MEMORY_REQUIRED = [
+  'confidence',
+  'importance',
+  'modality',
+  'subject',
+  'predicate',
+  'object',
+  'sentiment_polarity',
+  'sentiment_target',
+];
+
+const FALLBACK_REQUIRED_BY_TYPE = {
+  memory: ['slug', 'category', 'title', 'status', 'schema_version'],
+  skill: ['name', 'description'],
+  task: ['priority', 'category', 'status'],
+  assistant: ['name'],
+  workflow: ['name'],
+  rule: ['name'],
+  model: ['model_id', 'provider'],
+  conversation: ['thread_id'],
+  run: ['run_id', 'workflow_id'],
+  conflict: ['conflict_id', 'status', 'new_slug', 'existing_slug', 'detected_at'],
+  page: ['slug', 'name', 'sandbox_entry'],
+  migration: ['migration_id', 'from_version', 'to_version', 'status', 'description'],
+  release: ['release_id', 'version', 'schema_version', 'summary', 'released_at'],
+};
+
+let kernelPromise;
+
+function findRepoRoot(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    if (
+      fs.existsSync(path.join(dir, 'package.json')) &&
+      fs.existsSync(path.join(dir, 'src/core/schema.mjs'))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+async function loadKernel() {
+  if (kernelPromise) return kernelPromise;
+
+  kernelPromise = (async () => {
+    const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+    const roots = [process.cwd(), scriptDir]
+      .map(findRepoRoot)
+      .filter(Boolean);
+    const repoRoot = roots[0];
+    if (!repoRoot) return { repoRoot: null, schemas: null, validateMemoryNode: null };
+
+    try {
+      const schemaUrl = pathToFileURL(path.join(repoRoot, 'src/core/schema.mjs')).href;
+      const validatorUrl = pathToFileURL(
+        path.join(repoRoot, 'src/core/total-recall-memory-validator.mjs')
+      ).href;
+      const [{ SSSS_SCHEMAS }, { validateMemoryNode }] = await Promise.all([
+        import(schemaUrl),
+        import(validatorUrl),
+      ]);
+      return { repoRoot, schemas: SSSS_SCHEMAS, validateMemoryNode };
+    } catch {
+      return { repoRoot, schemas: null, validateMemoryNode: null };
+    }
+  })();
+
+  return kernelPromise;
+}
+
+function formatZodIssues(error) {
+  return (error?.issues || []).map((issue) => {
+    const field = issue.path?.length ? issue.path.join('.') : '(root)';
+    return `${field}: ${issue.message}`;
+  });
+}
+
+function addMissingFieldErrors(errors, data, fields) {
+  for (const field of fields) {
+    if (data[field] === undefined || data[field] === null || data[field] === '') {
+      errors.push(`Missing required field '${field}'.`);
+    }
+  }
+}
+
+function validateFallback(data, errors, warnings) {
+  if (!data.type) {
+    errors.push('Missing required frontmatter field: type.');
+    return;
+  }
+
+  if (typeof data.type !== 'string') {
+    errors.push('Frontmatter field type must be a string.');
+    return;
+  }
+
+  if (CONTRACT_ONLY_TYPES.has(data.type)) {
+    errors.push(
+      `Type '${data.type}' is a contract envelope type, not a Markdown document primitive.`
+    );
+    return;
+  }
+
+  const requiredFields = FALLBACK_REQUIRED_BY_TYPE[data.type];
+  if (!requiredFields) {
+    warnings.push(
+      `No local fallback schema for type '${data.type}'. Implementation registry was unavailable.`
+    );
+    return;
+  }
+
+  addMissingFieldErrors(errors, data, requiredFields);
+}
+
+function validateMemoryV2(data, errors) {
+  if (data.schema_version !== 2) {
+    errors.push(`Expected memory schema_version: 2, got: ${data.schema_version}`);
+    return;
+  }
+  addMissingFieldErrors(errors, data, V2_MEMORY_REQUIRED);
+}
+
+function validateMemoryPath(filePath, data, warnings) {
+  const normalized = filePath.split(path.sep).join('/');
+  if (!normalized.includes('/memory-vault/')) return;
+
+  const parent = path.basename(path.dirname(filePath));
+  if (data.category && parent !== data.category) {
+    warnings.push(
+      `Memory category '${data.category}' does not match parent directory '${parent}'.`
+    );
+  }
+}
+
 /**
- * Validates a single SSSS Markdown file against schema rules
+ * Validates a single SSSS Markdown file against the Total Recall implementation
+ * schema when available, with a scaffold-safe fallback for standalone installs.
  */
-export function validateNode(filePath) {
+export async function validateNode(filePath) {
+  const target = path.resolve(filePath);
+
   try {
-    const raw = fs.readFileSync(filePath, 'utf8');
-    const { data } = matter(raw);
+    const raw = fs.readFileSync(target, 'utf8');
+    const parsed = matter(raw);
+    const data = parsed.data || {};
     const errors = [];
+    const warnings = [];
+    const kernel = await loadKernel();
+
+    if (!raw.trimStart().startsWith('---')) {
+      errors.push('Missing YAML frontmatter block.');
+    }
+
+    if (data.type && CONTRACT_ONLY_TYPES.has(data.type)) {
+      errors.push(
+        `Type '${data.type}' is a contract envelope type, not a Markdown document primitive.`
+      );
+    } else if (data.type === 'memory' && kernel.validateMemoryNode) {
+      const result = kernel.validateMemoryNode(data);
+      if (!result.success) errors.push(...result.errors);
+    } else if (data.type && kernel.schemas?.[data.type]) {
+      const result = kernel.schemas[data.type].safeParse(data);
+      if (!result.success) errors.push(...formatZodIssues(result.error));
+    } else {
+      validateFallback(data, errors, warnings);
+      if (data.type === 'memory') validateMemoryV2(data, errors);
+    }
 
-    if (!data.type) errors.push('Missing "type" property.');
-    if (!data.slug) errors.push('Missing "slug" property.');
-    if (!data.category) errors.push('Missing "category" property.');
-    if (!data.title) errors.push('Missing "title" property.');
-    
-    if (data.schema_version !== 2) {
-      errors.push(`Expected schema_version: 2, got: ${data.schema_version}`);
+    if (APPEND_TYPES.has(data.type) && parsed.content.trim().length === 0) {
+      warnings.push(`Append-type '${data.type}' has an empty body.`);
     }
 
+    if (data.type === 'memory') validateMemoryPath(target, data, warnings);
+
     return {
       valid: errors.length === 0,
       errors,
-      file: filePath
+      warnings,
+      file: target,
+      type: data.type || null,
     };
   } catch (err) {
     return {
       valid: false,
       errors: [err.message],
-      file: filePath
+      warnings: [],
+      file: target,
+      type: null,
     };
   }
 }
 
-if (import.meta.url.startsWith('file:')) {
-  const runDirectly = process.argv[1] && process.argv[1].endsWith('validate-schema.mjs');
-  if (runDirectly) {
-    const target = process.argv[2];
-    if (!target) {
-      console.log('No file specified to validate.');
-      process.exit(0);
-    }
-    const res = validateNode(path.resolve(target));
-    if (res.valid) {
-      console.log(`✅ SSSS node "${path.basename(target)}" is fully valid!`);
-      process.exit(0);
-    } else {
-      console.error(`❌ Validation failed for "${path.basename(target)}":\n${res.errors.join('\n')}`);
-      process.exit(1);
-    }
+function realPathOrPath(value) {
+  try {
+    return fs.realpathSync(value);
+  } catch {
+    return value;
   }
 }
+
+const invokedPath = process.argv[1] ? realPathOrPath(path.resolve(process.argv[1])) : null;
+const modulePath = realPathOrPath(fileURLToPath(import.meta.url));
+if (invokedPath === modulePath) {
+  const target = process.argv[2];
+  if (!target) {
+    console.log('Usage: node validate-schema.mjs <path-to-ssss-node.md>');
+    process.exit(0);
+  }
+
+  const result = await validateNode(target);
+  if (result.warnings.length > 0) {
+    console.warn(`Warnings for ${path.basename(result.file)}:\n${result.warnings.join('\n')}`);
+  }
+
+  if (result.valid) {
+    console.log(`OK: SSSS node "${path.basename(result.file)}" is valid.`);
+    process.exit(0);
+  }
+
+  console.error(`FAIL: Validation failed for "${path.basename(result.file)}":\n${result.errors.join('\n')}`);
+  process.exit(1);
+}

package/src/cli/command.mjs

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveBrainLayer } from '../core/config.mjs';
+
+function printHelp() {
+  console.log(`
+  total-recall command — Manage project-local custom CLI commands
+
+  Usage:
+    total-recall command create <name> "<code>"   Create a new custom CLI command
+    total-recall command read <name>              Read the code of a custom CLI command
+    total-recall command update <name> "<code>"   Update an existing custom CLI command
+    total-recall command remove <name>            Remove a custom CLI command
+    total-recall command list                     List all custom CLI commands
+
+  Examples:
+    npx total-recall command create hello "console.log('Hello from the brain!');"
+    npx total-recall command read hello
+    npx total-recall command list
+`);
+}
+
+export default async function commandCmd(args) {
+  const action = args[0];
+  const name = args[1];
+
+  if (!action || action === '--help' || action === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (!name && action !== 'list') {
+    console.error(`Error: Missing command name.`);
+    console.error(`Usage: total-recall command ${action} <name>`);
+    process.exit(1);
+  }
+
+  // Ensure this is run in a project
+  let projectBrain;
+  try {
+    projectBrain = resolveBrainLayer('project');
+  } catch (err) {
+    console.error(`Error: You must be inside a Total Recall project to manage custom commands.`);
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  const commandsDir = path.join(projectBrain.agentDir, 'commands');
+
+  if (action === 'create') {
+    const code = args[2];
+    if (!code) {
+      console.error(`Error: Missing code snippet for the command.`);
+      console.error(`Usage: total-recall command create <name> "<code>"`);
+      process.exit(1);
+    }
+
+    if (!fs.existsSync(commandsDir)) {
+      fs.mkdirSync(commandsDir, { recursive: true });
+    }
+
+    const commandPath = path.join(commandsDir, `${name}.mjs`);
+    
+    // Wrap code in a default exported function for CLI execution
+    const fileContent = `// Auto-generated custom CLI command: ${name}
+export default async function run(args) {
+  ${code}
+}
+`;
+
+    fs.writeFileSync(commandPath, fileContent, 'utf8');
+    console.log(`\x1b[32m✔ Successfully created custom command: \x1b[1mnpx total-recall ${name}\x1b[0m`);
+    console.log(`  Saved to: ${commandPath}`);
+  } else if (action === 'read') {
+    const commandPath = path.join(commandsDir, `${name}.mjs`);
+    if (fs.existsSync(commandPath)) {
+      console.log(fs.readFileSync(commandPath, 'utf8'));
+    } else {
+      console.error(`Error: Custom command '${name}' does not exist.`);
+      process.exit(1);
+    }
+  } else if (action === 'update') {
+    const code = args[2];
+    if (!code) {
+      console.error(`Error: Missing code snippet for the command.`);
+      console.error(`Usage: total-recall command update <name> "<code>"`);
+      process.exit(1);
+    }
+
+    const commandPath = path.join(commandsDir, `${name}.mjs`);
+    if (!fs.existsSync(commandPath)) {
+      console.error(`Error: Custom command '${name}' does not exist.`);
+      process.exit(1);
+    }
+
+    // Wrap code in a default exported function for CLI execution
+    const fileContent = `// Auto-generated custom CLI command: ${name}
+export default async function run(args) {
+  ${code}
+}
+`;
+
+    fs.writeFileSync(commandPath, fileContent, 'utf8');
+    console.log(`\x1b[32m✔ Successfully updated custom command: \x1b[1m${name}\x1b[0m`);
+    console.log(`  Saved to: ${commandPath}`);
+  } else if (action === 'list') {
+    if (!fs.existsSync(commandsDir)) {
+      console.log('No custom commands found.');
+      return;
+    }
+    const files = fs.readdirSync(commandsDir).filter(f => f.endsWith('.mjs'));
+    if (files.length === 0) {
+      console.log('No custom commands found.');
+    } else {
+      console.log(`\x1b[1mCustom CLI commands in ${commandsDir}:\x1b[0m`);
+      files.forEach(f => {
+        console.log(`  - ${f.replace('.mjs', '')}`);
+      });
+    }
+  } else if (action === 'remove') {
+    const commandPath = path.join(commandsDir, `${name}.mjs`);
+    if (fs.existsSync(commandPath)) {
+      fs.unlinkSync(commandPath);
+      console.log(`\x1b[32m✔ Successfully removed custom command: \x1b[1m${name}\x1b[0m`);
+    } else {
+      console.error(`Error: Custom command '${name}' does not exist.`);
+      process.exit(1);
+    }
+  } else {
+    console.error(`Unknown action: ${action}`);
+    printHelp();
+    process.exit(1);
+  }
+}

package/src/cli/connect.mjs

@@ -62,13 +62,13 @@ const CLIENTS = {
   antigravity: {
     label: 'Antigravity',
     mode: 'symlink',
-    target: 'AGENTS.md',
+    target: '.agents/rules/AGENTS.md',
     writeSlashCommands: true
   },
   gemini: {
     label: 'Gemini',
     mode: 'symlink',
-    target: 'GEMINI.md',
+    target: '.agents/rules/GEMINI.md',
     writeSlashCommands: true
   },
   aider: {

package/src/core/runtime.mjs

@@ -317,10 +317,7 @@ export async function callLocalRuntime(prompt, system, config) {
       GITHUB_TOKEN: process.env.GITHUB_TOKEN || dynamicSecrets.github_token || githubToken,
     };
 
-    if (agent.name === 'antigravity' || agent.name === 'gemini') {
-      delete spawnEnv.GOOGLE_API_KEY;
-    }
-
+    logger.info('api', 'SPAWN_ENV GOOGLE_API_KEY length: ' + (spawnEnv.GOOGLE_API_KEY ? spawnEnv.GOOGLE_API_KEY.length : 0));
     const result = spawnSync('sh', ['-c', cmd], {
       encoding: 'utf8',
       timeout,

package/src/core/surface.mjs

@@ -424,7 +424,7 @@ async function writeShim(shimPath, skillsDir, nodes = [], { vaultDir, derivedDir
       if (stat.isSymbolicLink()) {
         // If it's a symlink, DO NOT destroy it. It likely points to INSTRUCTIONS.md natively,
         // and its content will update automatically when the target updates.
-        return;
+        return false;
       } else {
         const raw = fs.readFileSync(shimPath, 'utf8');
         let cleaned = raw;
@@ -435,15 +435,18 @@ async function writeShim(shimPath, skillsDir, nodes = [], { vaultDir, derivedDir
         
         const updated = injectDirectives(cleaned, rulesBlock);
         atomicWrite(shimPath, updated);
+        return true;
       }
     } else {
       if (!fs.existsSync(shimDir)) {
         fs.mkdirSync(shimDir, { recursive: true });
       }
       atomicWrite(shimPath, fullContent);
+      return true;
     }
   } catch (err) {
     // Ignore permission errors
+    return false;
   }
 }
 
@@ -453,8 +456,8 @@ async function writeShim(shimPath, skillsDir, nodes = [], { vaultDir, derivedDir
 const CLIENT_SHIMS = {
   cursor:        ['.cursorrules'],
   'claude-code': ['.clauderules'],
-  antigravity:   [],
-  gemini:        [],
+  antigravity:   ['AGENTS.md', '.agents/rules/AGENTS.md', '.agent/rules/AGENTS.md'],
+  gemini:        ['GEMINI.md', '.agents/rules/GEMINI.md', '.agent/rules/GEMINI.md'],
   codex:         ['.codexrules'],
   vscode:        ['.github/copilot-instructions.md', '.vscode/copilot-instructions.md'],
   pi:            [],
@@ -471,8 +474,20 @@ function readConnectedClients(clientsPath) {
     const raw = fs.readFileSync(clientsPath, 'utf8').trim();
     if (!raw) return null;
     const parsed = JSON.parse(raw);
-    if (!Array.isArray(parsed) || parsed.length === 0) return null;
-    return new Set(parsed.map(String));
+    
+    // Support object format: { clients: { gemini: {...} } }
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && parsed.clients) {
+      const keys = Object.keys(parsed.clients);
+      if (keys.length === 0) return null;
+      return new Set(keys);
+    }
+    
+    // Support legacy array format just in case
+    if (Array.isArray(parsed) && parsed.length > 0) {
+      return new Set(parsed.map(String));
+    }
+    
+    return null;
   } catch {
     return null;
   }
@@ -484,9 +499,12 @@ function readConnectedClients(clientsPath) {
 async function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultDir, derivedDir } = {}) {
   const agentDir = path.dirname(instructionsFile);
   const baseDir = path.basename(agentDir) === '.agent' ? path.dirname(agentDir) : agentDir;
+  let injectedCount = 0;
 
   // Always write the canonical INSTRUCTIONS.md
-  await writeShim(path.join(baseDir, 'INSTRUCTIONS.md'), skillsDir, nodes, { vaultDir, derivedDir });
+  if (await writeShim(path.join(baseDir, 'INSTRUCTIONS.md'), skillsDir, nodes, { vaultDir, derivedDir })) {
+    injectedCount++;
+  }
 
   // Determine which client shims to write
   const clientsPath = path.join(baseDir, '.agent', 'config', 'clients.json');
@@ -498,10 +516,14 @@ async function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultD
       const files = CLIENT_SHIMS[client];
       if (!files) continue;
       for (const file of files) {
-        await writeShim(path.join(baseDir, file), skillsDir, nodes, { vaultDir, derivedDir });
+        if (await writeShim(path.join(baseDir, file), skillsDir, nodes, { vaultDir, derivedDir })) {
+          injectedCount++;
+        }
       }
     }
   }
+  
+  return injectedCount;
 }
 
 /**
@@ -529,7 +551,7 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
   }
 
   // 1. Write pointer and active rules to all instruction shims
-  await compilePointers(instructionsFile, skillsDir, nodes, { vaultDir, derivedDir });
+  const skillsInjected = await compilePointers(instructionsFile, skillsDir, nodes, { vaultDir, derivedDir });
 
   // 2. Build derived indexes (powers semantic search API)
   if (!fs.existsSync(derivedDir)) {
@@ -569,7 +591,7 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
 
   return {
     nodesProcessed: nodes.length,
-    skillsInjected: 0,
+    skillsInjected,
     semanticIndexed: semanticResult.indexed,
     semanticUnavailable: semanticResult.unavailable
   };