total-recall-brain 3.40.7 → 3.41.0

package/scaffold/.agent/skills/plugins/references/optimized/original.md

@@ -1,58 +0,0 @@
----
-name: plugins
-description: Create, validate, install, run, and share Total Recall plugins. Use when a user wants a plugin that adds a useful command, scheduled task, agent context, or SSSS memory category.
----
-
-# Total Recall plugins
-
-Build a plugin for a concrete user job. Start by stating the command, context, task, or memory category it adds and how a user will tell that it works. Do not add a plugin solely to populate a gallery.
-
-## Where to work
-
-Run `total-recall plugin create <id> --name "..." --description "..." --use-case <tag> --with-cli` to scaffold an installed plugin. The CLI creates a directory under the current project's `.agent/skills/total-recall/plugins/`; `--global` creates a machine-wide plugin. A plugin is a folder containing `plugin.json` and the files its manifest names. For a plugin intended to ship with Total Recall itself, use the package's `plugins/<id>/` folder and add a real install and use test.
-
-Inspect the installed package's `metadata.plugin.schema.json` and `src/core/plugin-loader.mjs` for the current executable contract before changing a manifest. The schema supports:
-
-```json
-{
-  "id": "example-plugin",
-  "name": "Example Plugin",
-  "version": "1.0.0",
-  "description": "The specific job this plugin does.",
-  "author": "Author name",
-  "license": "MIT",
-  "use_cases": ["research"],
-  "cli": {
-    "command": "example-plugin",
-    "handler": "./cli.mjs",
-    "subcommands": [{ "name": "status", "description": "Show current status" }]
-  }
-}
-```
-
-An ID is lowercase kebab case, starts with a letter, and is 2–64 characters. `use_cases` are descriptive kebab-case tags. Keep the manifest honest: declare only features the plugin implements. `README.md` should explain the user job, prerequisites, commands, outputs, and any data or network access.
-
-## Implement a capability
-
-- **Command:** export `async function run(argv)` from the `cli.handler` module. It receives `['node', 'total-recall', '<command>', '<subcommand>', ...]`. A default-exported function is also supported and receives arguments after the command. Return a result or set `process.exitCode` on failure. The runner isolates the handler in a child process, with a timeout and output cap.
-- **Scheduled task:** add `tasks: [{ "intent": "...", "schedule": "*/15 * * * *", "command": "sample" }]`. `command` is a subcommand implemented by the plugin's CLI handler. The daemon runs it once per due minute slot and records the outcome as a `plugin.task_run` event. Keep tasks bounded and idempotent.
-- **Agent context:** add `compile: { "generator": "./generator.mjs", "auto": true }` and export `generateContext()` from that file. Only include information useful to the agent; avoid secrets and noisy telemetry.
-- **Memory category:** declare it under `ssss_schemas.categories` using the current manifest schema. Preserve SSSS Markdown and operation-contract writes; do not write vault documents directly.
-
-- **Repo-customized skill:** a layered skill (plugin-owned `core/`, repo-owned files beside it) declares its repo config contract as `core/config.schema.json`, a JSON Schema whose root is an object. Annotate an array with `"x-collection": "<noun>"` (and optionally `"x-key"`, default `name`) to get `<noun> list|add|remove`. An optional `core/detect.mjs` exports `detect({ repoRoot, skillDir })` and returns a proposed config. Users customize the repo layer with `total-recall skill config <id> config set …`, `detect --apply`, or `init`, or with a repo command generated by `total-recall command create <name> --config-for-skill <id>`. Every write validates the whole config and commits a `skill_config` record to the repo's project vault; `config.json` is rebuilt from it. Never tell users to edit `config.json` by hand: `config validate` reports hand edits as drift, and `config import` adopts a pre-existing file. Mark gate-command string fields `"x-command": true`; `skill config <id> check`, `skill status <id>`, and `app verify` confirm each one resolves without running it.
-
-- **App-runtime CLI:** declare `app_cli` in `plugin.json`: `name`, `api: { base_url_env, default_base_url }` (loopback only; operators override it with the env var or `--base-url`), optional `auth: { type: "bearer", token_env }`, and `commands: [{ name, method, path, args }]`. Args are typed (`string|integer|number|boolean`, `choices`, `default`, `required`, `positional`); `{name}` in `path` must be a required arg, other args go to the query (GET/DELETE) or JSON body. `total-recall app cli <plugin> --lang node|python` (or `--adapter flask|nextjs|react|ssss-app`) prints a self-contained file; `--out <file>` writes it. The file runs without Total Recall: exit 0 ok, 1 the app returned an error, 2 usage, 3 unreachable; `--json` prints `{ ok, status, data | error }`. Regenerate after changing the spec; never hand-edit the output.
-- **UI elements:** author each element once as a self-contained custom element: an ES module under the plugin (e.g. `ui/<id>.js`) that imports nothing, calls `customElements.define('<tag>', …)` exactly once, and styles itself only with design-token variables (`var(--color-…)`, `--spacing-…`, `--radius-…`, `--typography-<style>-…`, `--font-family-…`; `--_name` for private ones). No literal colors, not even as `var()` fallbacks. Declare it in `plugin.json` `ui.elements[]`: `id`, `kind` (`panel|form|list|detail|settings|widget`), `tag`, `module`, optional `slot`, typed `props` (set as DOM properties), `events`, the `tokens` it requires and `optional_tokens` it uses with a token fallback; `ui.design_tokens` may point at a neutral default `DESIGN.md`. `total-recall app ui <plugin> --ui web-components|react` (or `--adapter flask|ssss-app|nextjs|react`) with `--tokens <app DESIGN.md>` checks the required tokens and generates `tokens.css`, `elements/<id>.js`, `index.js`, React wrappers (`--typescript` for `.tsx` plus `.d.ts`), and `ui-manifest.json`; `--out <dir>` writes `<dir>/<plugin-id>/`. An app restyles elements by editing its `DESIGN.md` and regenerating; the element files do not change.
-
-## Validate the actual job
-
-1. Validate `plugin.json` against the installed schema and `total-recall plugin info <id>`.
-2. Install in a clean temporary project, then run the declared command through `total-recall <command> <subcommand>`. For tasks, verify one due run and its event. For context generators, compile and inspect the resulting block.
-3. Exercise failure paths: missing prerequisite, invalid input, timeout, and any network failure. A plugin that installs but cannot do its advertised job is unfinished.
-4. Review the plugin's file set before sharing. Plugin code has the recipient's process permissions when run. Never bundle secrets, browser profiles, vault data, or machine-specific paths.
-
-## Share with another user
-
-`total-recall plugin share <id>` marks an installed plugin shareable. Configure `TR_PUBLIC_BASE_URL` as the node's externally reachable HTTPS origin; the command and dashboard then show a direct link ending in `#sha256=<content hash>`. Send that link to the recipient. They install with `total-recall plugin install '<link>'`. The installer requires HTTPS, rejects private destination addresses and redirects, caps the bundle size, and verifies the pinned SHA-256 before writing files. There is no central catalog. The hosting node must actually be reachable at its configured HTTPS origin.
-
-`total-recall plugin unshare <id>` stops serving the bundle. Existing installations remain on recipients' machines. Users on one private mesh may also use `peer:<host>/<id>`; mesh membership is not required for public sharing.

package/scaffold/.agent/skills/plugins/references/optimized/section-01.md

@@ -1,5 +0,0 @@
-
-# Total Recall plugins
-
-Build a plugin for a concrete user job. Start by stating the command, context, task, or memory category it adds and how a user will tell that it works. Do not add a plugin solely to populate a gallery.
-

package/scaffold/.agent/skills/plugins/references/optimized/section-02.md

@@ -1,25 +0,0 @@
-## Where to work
-
-Run `total-recall plugin create <id> --name "..." --description "..." --use-case <tag> --with-cli` to scaffold an installed plugin. The CLI creates a directory under the current project's `.agent/skills/total-recall/plugins/`; `--global` creates a machine-wide plugin. A plugin is a folder containing `plugin.json` and the files its manifest names. For a plugin intended to ship with Total Recall itself, use the package's `plugins/<id>/` folder and add a real install and use test.
-
-Inspect the installed package's `metadata.plugin.schema.json` and `src/core/plugin-loader.mjs` for the current executable contract before changing a manifest. The schema supports:
-
-```json
-{
-  "id": "example-plugin",
-  "name": "Example Plugin",
-  "version": "1.0.0",
-  "description": "The specific job this plugin does.",
-  "author": "Author name",
-  "license": "MIT",
-  "use_cases": ["research"],
-  "cli": {
-    "command": "example-plugin",
-    "handler": "./cli.mjs",
-    "subcommands": [{ "name": "status", "description": "Show current status" }]
-  }
-}
-```
-
-An ID is lowercase kebab case, starts with a letter, and is 2–64 characters. `use_cases` are descriptive kebab-case tags. Keep the manifest honest: declare only features the plugin implements. `README.md` should explain the user job, prerequisites, commands, outputs, and any data or network access.
-

package/scaffold/.agent/skills/plugins/references/optimized/section-03.md

@@ -1,12 +0,0 @@
-## Implement a capability
-
-- **Command:** export `async function run(argv)` from the `cli.handler` module. It receives `['node', 'total-recall', '<command>', '<subcommand>', ...]`. A default-exported function is also supported and receives arguments after the command. Return a result or set `process.exitCode` on failure. The runner isolates the handler in a child process, with a timeout and output cap.
-- **Scheduled task:** add `tasks: [{ "intent": "...", "schedule": "*/15 * * * *", "command": "sample" }]`. `command` is a subcommand implemented by the plugin's CLI handler. The daemon runs it once per due minute slot and records the outcome as a `plugin.task_run` event. Keep tasks bounded and idempotent.
-- **Agent context:** add `compile: { "generator": "./generator.mjs", "auto": true }` and export `generateContext()` from that file. Only include information useful to the agent; avoid secrets and noisy telemetry.
-- **Memory category:** declare it under `ssss_schemas.categories` using the current manifest schema. Preserve SSSS Markdown and operation-contract writes; do not write vault documents directly.
-
-- **Repo-customized skill:** a layered skill (plugin-owned `core/`, repo-owned files beside it) declares its repo config contract as `core/config.schema.json`, a JSON Schema whose root is an object. Annotate an array with `"x-collection": "<noun>"` (and optionally `"x-key"`, default `name`) to get `<noun> list|add|remove`. An optional `core/detect.mjs` exports `detect({ repoRoot, skillDir })` and returns a proposed config. Users customize the repo layer with `total-recall skill config <id> config set …`, `detect --apply`, or `init`, or with a repo command generated by `total-recall command create <name> --config-for-skill <id>`. Every write validates the whole config and commits a `skill_config` record to the repo's project vault; `config.json` is rebuilt from it. Never tell users to edit `config.json` by hand: `config validate` reports hand edits as drift, and `config import` adopts a pre-existing file. Mark gate-command string fields `"x-command": true`; `skill config <id> check`, `skill status <id>`, and `app verify` confirm each one resolves without running it.
-
-- **App-runtime CLI:** declare `app_cli` in `plugin.json`: `name`, `api: { base_url_env, default_base_url }` (loopback only; operators override it with the env var or `--base-url`), optional `auth: { type: "bearer", token_env }`, and `commands: [{ name, method, path, args }]`. Args are typed (`string|integer|number|boolean`, `choices`, `default`, `required`, `positional`); `{name}` in `path` must be a required arg, other args go to the query (GET/DELETE) or JSON body. `total-recall app cli <plugin> --lang node|python` (or `--adapter flask|nextjs|react|ssss-app`) prints a self-contained file; `--out <file>` writes it. The file runs without Total Recall: exit 0 ok, 1 the app returned an error, 2 usage, 3 unreachable; `--json` prints `{ ok, status, data | error }`. Regenerate after changing the spec; never hand-edit the output.
-- **UI elements:** author each element once as a self-contained custom element: an ES module under the plugin (e.g. `ui/<id>.js`) that imports nothing, calls `customElements.define('<tag>', …)` exactly once, and styles itself only with design-token variables (`var(--color-…)`, `--spacing-…`, `--radius-…`, `--typography-<style>-…`, `--font-family-…`; `--_name` for private ones). No literal colors, not even as `var()` fallbacks. Declare it in `plugin.json` `ui.elements[]`: `id`, `kind` (`panel|form|list|detail|settings|widget`), `tag`, `module`, optional `slot`, typed `props` (set as DOM properties), `events`, the `tokens` it requires and `optional_tokens` it uses with a token fallback; `ui.design_tokens` may point at a neutral default `DESIGN.md`. `total-recall app ui <plugin> --ui web-components|react` (or `--adapter flask|ssss-app|nextjs|react`) with `--tokens <app DESIGN.md>` checks the required tokens and generates `tokens.css`, `elements/<id>.js`, `index.js`, React wrappers (`--typescript` for `.tsx` plus `.d.ts`), and `ui-manifest.json`; `--out <dir>` writes `<dir>/<plugin-id>/`. An app restyles elements by editing its `DESIGN.md` and regenerating; the element files do not change.
-

package/scaffold/.agent/skills/plugins/references/optimized/section-04.md

@@ -1,7 +0,0 @@
-## Validate the actual job
-
-1. Validate `plugin.json` against the installed schema and `total-recall plugin info <id>`.
-2. Install in a clean temporary project, then run the declared command through `total-recall <command> <subcommand>`. For tasks, verify one due run and its event. For context generators, compile and inspect the resulting block.
-3. Exercise failure paths: missing prerequisite, invalid input, timeout, and any network failure. A plugin that installs but cannot do its advertised job is unfinished.
-4. Review the plugin's file set before sharing. Plugin code has the recipient's process permissions when run. Never bundle secrets, browser profiles, vault data, or machine-specific paths.
-

package/scaffold/.agent/skills/plugins/references/optimized/section-05.md

@@ -1,5 +0,0 @@
-## Share with another user
-
-`total-recall plugin share <id>` marks an installed plugin shareable. Configure `TR_PUBLIC_BASE_URL` as the node's externally reachable HTTPS origin; the command and dashboard then show a direct link ending in `#sha256=<content hash>`. Send that link to the recipient. They install with `total-recall plugin install '<link>'`. The installer requires HTTPS, rejects private destination addresses and redirects, caps the bundle size, and verifies the pinned SHA-256 before writing files. There is no central catalog. The hosting node must actually be reachable at its configured HTTPS origin.
-
-`total-recall plugin unshare <id>` stops serving the bundle. Existing installations remain on recipients' machines. Users on one private mesh may also use `peer:<host>/<id>`; mesh membership is not required for public sharing.

package/scaffold/.agent/skills/total-recall/openwiki/README.md

@@ -1,10 +0,0 @@
-# OpenWiki
-
-Portable knowledge documentation for this Total Recall brain.
-
-| Layer | Purpose |
-|-------|---------|
-| **Memory vault** | SSSS nodes (rules, prefs, facts) — machine-enforceable |
-| **OpenWiki** | Human/agent docs (architecture, how-tos, stack notes) |
-
-OpenWiki ships with Total Recall. Edit freely; do not put secrets here.

package/scaffold/.agent/skills/total-recall/openwiki/architecture.md

@@ -1,5 +0,0 @@
-# Architecture (this brain)
-
-Describe the systems this brain cares about: repos, stacks, deploy targets.
-
-Project brains should document the local codebase; the global brain documents cross-repo identity and preferences.

package/scaffold/.agent/skills/total-recall/openwiki/ide.md

@@ -1,10 +0,0 @@
-# IDE personalization
-
-```bash
-npx total-recall connect claude-code   # CLAUDE.md
-npx total-recall connect codex         # AGENTS.md
-npx total-recall connect cursor        # .cursor/rules/
-npx total-recall connect gemini        # GEMINI.md
-```
-
-Total Recall only writes inside managed inject markers. Your local rules stay intact.

package/scaffold/.agent/skills/total-recall/openwiki/memory.md

@@ -1,11 +0,0 @@
-# Memory
-
-Use the Total Recall CLI for durable memory:
-
-```bash
-npx total-recall remember invariant "Never commit secrets." --importance 5
-npx total-recall recall "secrets"
-npx total-recall compile
-```
-
-Categories: invariants, preferences, facts, decisions, patterns, anti-patterns, concepts, lore.

package/scaffold/.agent/skills/total-recall/openwiki/secrets.md

@@ -1,7 +0,0 @@
-# Secrets & API keys
-
-Store credentials in Total Recall's secrets store (`config/secrets.enc` / future CLI).
-
-**Never** put API keys in openwiki pages or compiled IDE instruction files.
-
-Planned CLI surface (TR_CORE_FOCUS Phase 4): `secret set|list|rotate|audit` and usage/cost meters.

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

@@ -1,7 +0,0 @@
-# Skills
-
-- **Total Recall skill** (only nested agent skill): `.agent/skills/total-recall/SKILL.md`
-- **User skills**: `.agent/skills/<name>/SKILL.md` — project or global
-- **TR modules** (not skills): `.agent/skills/total-recall/modules/` — internal docs/scripts
-
-TR will track skill installs across repos and support adaptive deploy (see TR_CORE_FOCUS).

package/scaffold/openwiki/README.md

@@ -1,10 +0,0 @@
-# OpenWiki
-
-Portable knowledge documentation for this Total Recall brain.
-
-| Layer | Purpose |
-|-------|---------|
-| **Memory vault** | SSSS nodes (rules, prefs, facts) — machine-enforceable |
-| **OpenWiki** | Human/agent docs (architecture, how-tos, stack notes) |
-
-OpenWiki ships with Total Recall. Edit freely; do not put secrets here.

package/scaffold/openwiki/architecture.md

@@ -1,5 +0,0 @@
-# Architecture (this brain)
-
-Describe the systems this brain cares about: repos, stacks, deploy targets.
-
-Project brains should document the local codebase; the global brain documents cross-repo identity and preferences.

package/scaffold/openwiki/ide.md

@@ -1,10 +0,0 @@
-# IDE personalization
-
-```bash
-npx total-recall connect claude-code   # CLAUDE.md
-npx total-recall connect codex         # AGENTS.md
-npx total-recall connect cursor        # .cursor/rules/
-npx total-recall connect gemini        # GEMINI.md
-```
-
-Total Recall only writes inside managed inject markers. Your local rules stay intact.

package/scaffold/openwiki/memory.md

@@ -1,11 +0,0 @@
-# Memory
-
-Use the Total Recall CLI for durable memory:
-
-```bash
-npx total-recall remember invariant "Never commit secrets." --importance 5
-npx total-recall recall "secrets"
-npx total-recall compile
-```
-
-Categories: invariants, preferences, facts, decisions, patterns, anti-patterns, concepts, lore.

package/scaffold/openwiki/secrets.md

@@ -1,7 +0,0 @@
-# Secrets & API keys
-
-Store credentials in Total Recall's secrets store (`config/secrets.enc` / future CLI).
-
-**Never** put API keys in openwiki pages or compiled IDE instruction files.
-
-Planned CLI surface (TR_CORE_FOCUS Phase 4): `secret set|list|rotate|audit` and usage/cost meters.

package/scaffold/openwiki/skills.md

@@ -1,7 +0,0 @@
-# Skills
-
-- **Total Recall skill** (only nested agent skill): `.agent/skills/total-recall/SKILL.md`
-- **User skills**: `.agent/skills/<name>/SKILL.md` — project or global
-- **TR modules** (not skills): `.agent/skills/total-recall/modules/` — internal docs/scripts
-
-TR will track skill installs across repos and support adaptive deploy (see TR_CORE_FOCUS).