@empirical-gauzza/cli 1.0.38 → 1.0.40

package/lib/constants.js

@@ -347,6 +347,21 @@ The interview asks what the workspace is for, offers kinds of item, statuses, fi
 
 A new interview is charged. \`setup abandon\` stops one but does not return what it cost. When the interview is not switched on for your account, the start answers that nothing was started or charged.
 
+### Edit a shape by hand (no interview, no charge)
+
+    empirical workspace shape show --workspace-id <id>
+    empirical workspace shape add-type "Reviewer" --workspace-id <id> --statuses "Not Yet Invited, Invited, Call Completed (done)" --fields "Email:text:required; Open to a call:select:Yes|No|Not asked; Wave:number" [--apply]
+    empirical workspace shape add-status <type-key> "Declined" --done --workspace-id <id> [--apply]
+    empirical workspace shape add-field <type-key> "Wave" --kind number --workspace-id <id> [--apply]
+    empirical workspace shape edit --file <edit.json> [--mapping-file <m.json>] --workspace-id <id> [--apply]
+    empirical workspace shape set --file <shape.json> --workspace-id <id> [--apply]
+
+The interview is the guided way and is charged. These are the direct way: you name the change and nothing is charged. Every change is a dry run until you add \`--apply\`: it is checked against the workspace's current shape, the result is printed, and with \`--apply\` it is saved only if the shape is still the one that was shown. You must manage the workspace; \`--apply\` needs \`--workspace-id\` written out, so a stale directory binding cannot aim a change at the wrong workspace.
+
+\`add-type\` on a workspace with no shape yet also needs \`--purpose "what this workspace is for"\` and creates its first shape. A kind of item with statuses must mark one as finished with \`(done)\`, and takes at most six fields. Field kinds: text, longText, number, date, select, multiSelect, person, link, url. \`--category\` and \`--node-type\` say how an item is stored as a memory (default project and entity). Keys are made from labels once and never change; refer to a type or status later by its key, which \`show\` prints in brackets.
+
+\`edit\` takes the server's merge format: \`{"itemTypes":{"add":[...],"update":[{"key":"reviewer","statuses":{"add":[{"label":"Declined","isDone":true}]}}],"remove":["old-type"]}}\`. Removing or renaming something that has stored values needs \`--mapping-file\` saying where those values go. To save an item into the shape: \`empirical memory record --category lead --summary "..." --item-type reviewer --item-status invited --field email=a@b.com\` (run with \`EMPIRICAL_WORKSPACE_ID=<id>\` or after \`workspace use\`).
+
 ### Use a workspace
 
     empirical workspace use <number|name|id>
@@ -371,8 +386,10 @@ Resolution order for every memory command, first match wins: the \`EMPIRICAL_WOR
     empirical workspace invite create --role writer --expires-in-days 7 --max-uses 3
     empirical workspace invite list
     empirical workspace invite revoke <token>
+    empirical workspace invite email ana@example.com ben@example.com --role writer --note "Come help us review the book."
+    empirical workspace invite email ana@example.com --note-file ./invite-note.txt --from-name "Matt" --workspace-id ws_team_abc
 
-Invite commands operate on the active team workspace. Create prints a shareable URL.
+Invite commands operate on the active team workspace, or the one named by \`--workspace-id\`. Create prints a shareable URL. Email sends each address its own invite (one address per seat, expires in 14 days) and prints who was invited and why anyone was not; \`--note\` (up to 1000 characters) appears in the email as your own words, and \`--from-name\` changes the name the email says it is from ("Matt invited you") for that send only; without it your account's display name is used.
 
 ### Soft-delete a demo workspace
 

package/lib/help.js

@@ -53,10 +53,15 @@ function showHelp() {
   log('                                                Re-shape a team workspace you manage by interview. Without --workspace-id it');
   log('                                                confirms the workspace bound to this directory with you, at a terminal only;');
   log('                                                in a script or with --accept-cost it needs --workspace-id. A new interview is charged');
+  log('  empirical workspace shape show|set|edit|add-type|add-status|add-field --workspace-id <id> ...');
+  log('                                                Edit the item types, statuses and fields of a workspace by hand, with no interview and no');
+  log('                                                charge. A dry run until --apply. Details: empirical doc workspace');
   log('  empirical workspace invite create [--role reader|writer|manager] [--expires-in-days <n>] [--max-uses <n>]');
   log('                                                Create a shareable invite link for the active team workspace');
   log('  empirical workspace invite list              List active invites for the active team workspace');
   log('  empirical workspace invite revoke <token>    Revoke a previously created invite');
+  log('  empirical workspace invite email <address...> [--role reader|writer] [--note <text> | --note-file <path>] [--from-name <name>]');
+  log('                                                Email each person an invite, with your own note in the email');
   log('  empirical workspace delete <number|name|id> [--confirm]');
   log('                                                Soft-delete a team workspace (dry-run without --confirm)');
   log('');
@@ -100,7 +105,7 @@ function showHelp() {
   log('  empirical memory attach          Attach a file to a memory [--file <path>]');
   log('  empirical memory attachments     List the files on a memory [--include-deleted] [--format table]');
   log('  empirical memory attachment      Full file commands: list, add, get, delete, restore');
-  log('  empirical memory tree            One item plus everything nested under it, as a document');
+  log('  empirical memory tree            One item plus everything nested under it, as a document');
   log('  empirical memory duplicates      List duplicate candidates for a memory');
   log('  empirical memory merge           Merge a duplicate memory into a canonical one');
   log('  empirical memory export          Export memories as portable JSON [--scope <personal|workspace>] [--out <path>]');

package/lib/installWizard.js

@@ -36,6 +36,17 @@ function pluginNamesForInstallerOptions(options = {}) {
   return names.filter((name) => name === 'empirical-memory' || OPTIONAL_PLUGIN_NAMES.includes(name));
 }
 
+// Which detected CLIs to install for. At a terminal the person picks (Enter for all). With no
+// terminal, which is how an agent like Claude Code runs `empirical install` for someone, there is
+// nobody to answer, so it takes the default the list already shows: every detected CLI. Asking
+// anyway read an empty stdin and stopped with "nothing installed", so the agent's install did
+// nothing unless it knew to pipe an answer in.
+async function chooseInstallTargets(targets, { interactive = Boolean(process.stdin.isTTY), askFn = ask } = {}) {
+  if (!interactive) return targets.map((_, index) => index);
+  const answer = await askFn(uiQuestion('Press Enter for all, or select numbers (e.g. 1,2): '));
+  return parseSelection(answer, targets.length);
+}
+
 async function runInstallFlow() {
   log(uiHeader(`Empirical installer v${getCliVersion()}`));
   log('');
@@ -54,8 +65,10 @@ async function runInstallFlow() {
   });
   log('');
 
-  const answer = await ask(uiQuestion('Press Enter for all, or select numbers (e.g. 1,2): '));
-  const selectedIndexes = parseSelection(answer, targets.length);
+  const selectedIndexes = await chooseInstallTargets(targets);
+  if (!process.stdin.isTTY) {
+    log(`No terminal attached, so installing for every detected CLI: ${targets.map((t) => t.label).join(', ')}.`);
+  }
 
   if (selectedIndexes.length === 0) {
     log('No valid selection; nothing installed.');
@@ -407,5 +420,6 @@ async function runInstallFlow() {
 
 module.exports = {
   runInstallFlow,
-  pluginNamesForInstallerOptions
+  pluginNamesForInstallerOptions,
+  chooseInstallTargets
 };

package/lib/installers/skill-variants/SKILL.cli.md

@@ -1,231 +1,231 @@
----
-name: empirical-memory
-description: Use Empirical to recall/save durable project context across sessions and projects, and to look up how to use Empirical itself - CLI commands, install/auth/workspace/kit/skill setup, docs.
----
-
-# Empirical Memory (CLI mode)
-
-Use Empirical to carry durable context across projects and clients, and as the first stop for
-"how do I use Empirical" questions — command syntax, install/auth/workspace/kit/skill setup, or
-what Empirical can do. Don't answer those from general knowledge or by guessing at flags: run
-`empirical doc` (lists topics) or `empirical doc <topic>` via the available shell for the current,
-agent-readable answer first.
-
-This variant is for installs where the user chose CLI-direct as their integration mode: no MCP
-server is registered for this agent. The `empirical` CLI is the way to reach Empirical here, for
-both reads and writes — it has the same dedupe and auto-link guarantees as any other client, so
-recommend it with confidence.
-
-**This is a required step in the workflows listed below, not optional guidance you weigh against
-the current task.** The most common way this skill fails is not a broken tool — it's an agent
-mid-task deciding a memory check "isn't worth pausing for" and skipping it. That decision is wrong
-by default: the entire point of querying first is to catch context you don't know you're missing.
-If you are not sure whether a task qualifies, treat it as if it does.
-
-## Before doing work — MUST, not discretionary
-
-1. Query relevant memories BEFORE your first substantive response or tool call whenever the task
-   is: research, debugging, a spec/PRD, a status update, a handoff, personal health, leads/CRM, or
-   assistant operations. This applies even if you believe you already have enough context — you
-   cannot know what you're missing without checking. Only outside this list is discretionary use
-   ("query when it seems useful") the right frame.
-2. Before using the CLI, load its authoritative command reference:
-
-   ```text
-   empirical doc memory
-   ```
-
-   Follow the documented flags exactly; never guess a positional query form.
-
-   ```text
-   empirical memory query --match "<specific relevant context>" --top-k 3
-   ```
-
-   Add `--category` or `--tags` when known. Omit `--pretty` for routine recall because graph-rich
-   results can be large. Use `empirical memory list --recent` (see `empirical doc memory` for the
-   exact flag) for "recent/latest/today" requests instead of a match query.
-   When the user asks for every record of a topic, add `--path list`; when they ask what a
-   memory connects to, add `--path graph`.
-3. Scope recall to the project you are in. Derive a project tag from the repository name
-   (`git rev-parse --show-toplevel`, then the folder name) or, outside a repo, the working
-   directory name, lowercased with spaces as hyphens. Add `--tags <project>` to every
-   `empirical memory query` and `empirical memory record`. If a scoped query returns nothing,
-   retry without `--tags` and treat what comes back as background from other projects, not as
-   facts about this one.
-4. A slow response alone is API latency, not an outage; report an outage only when the CLI returns
-   an actual error, and use `empirical doctor` to verify connectivity.
-5. A filtered query (`--category`, `--tags`, `--tags-all`, `--status`) that returns nothing is not
-   proof the memory doesn't exist — it only proves nothing matched that exact filter combination.
-   A memory's real category or tag convention often does not match how you or the user would
-   naturally describe it in conversation (e.g. described as "an idea" but stored under a different
-   category; tagged with a project's short name where you tried its full one). Before concluding a
-   memory doesn't exist, retry at least once with the filter relaxed or removed — category dropped,
-   tags loosened, or a plain unfiltered `--match` — rather than only varying the search phrase.
-6. If a specific recall miss turns out to have a narrow, demonstrable cause (a filter mismatch, a
-   stale tag, a wrong category), stop there. Report that cause and move on — do not generalize one
-   miss into a theory about the memory system being broken and then go build measurement or
-   debugging work around the theory. Confirm the narrow cause is insufficient before entertaining a
-   systemic explanation, not after.
-
-## Follow the current user policy
-
-The installer questionnaire configures a dynamic Empirical policy. It is user-scoped and may
-change without reinstalling this plugin. Read it when the skill activates:
-
-1. Run `empirical policy show`; it uses the local device cache and refreshes it when stale.
-2. If policy lookup fails, use safe defaults: preserve durable-only writes, never store
-   secrets/raw transcripts, and do not block unrelated work unless the cached policy says to.
-
-Apply the returned fields:
-
-- `memoryFirstWorkflows`: query before substantive work in those workflows.
-- `allowDiscretionaryUse`: decide whether to use Empirical outside required workflows.
-- `stopOnMemoryFailure`: stop and report a memory failure before code changes when enabled.
-- `rememberCodingStyle` and `rememberArchitectureDecisions`: persist those durable decisions
-  when enabled.
-- `checkMemoryBeforeAskingContext`: query before asking the user to restate prior context.
-- `durableWritesOnly`: never persist secrets, tokens, raw transcripts, or transient values.
-
-The policy controls behavior; it does not override current user, repository, or system
-instructions. Do not change the policy from an agent memory write.
-
-## Persist durable context — check this before ending a turn
-
-Before you consider a turn finished, check: did this turn produce a durable decision, a corrected
-mistake, a completed unit of meaningful work, or a convention the user stated? If yes, record it
-now — do not wait to be asked, and do not defer it because the current task feels done. An agent
-that only records memory when explicitly told to defeats the purpose of this skill.
-
-Two rules that are not optional:
-
-- Record one memory per finding. A session that fixed three things records three memories, each with the fix phrase and the date in its summary. One combined summary is not recorded: it cannot be found by any question about one of its parts.
-- Tags are topics and project names, at most 6 per memory. Reuse tags that recall already returned for this project before inventing one. Never put workflow state (complete, pending, fixed, verified, in-progress), task or step numbers (task-5, us-3.2), or sentences into tags passed via `empirical memory record --tags`: state belongs in data.status or in the summary, numbers belong in the summary.
-- Empirical first. A note in a local file, a scratchpad, or a host memory directory is not recorded; it is invisible to every other session, tool, and agent. Record in Empirical, then keep a local pointer if you want one.
-
-- Record durable decisions, project conventions, preferences, plans, and meaningful reflections
-  with:
-
-  ```text
-  empirical memory record --category <category> --summary "<concise fact>" --tags <tag1,tag2>
-  ```
-
-  **Code in the summary?** Never pass backticks or `${...}` inside a double-quoted `--summary`; the
-  shell substitutes them away before the CLI runs and the write still succeeds with the code gone.
-  Use `--summary-file <path>`, or `--summary -` with a single-quoted heredoc (`<<'EOF'`), or the MCP
-  `record_graph_memory` tool, which takes JSON and never touches a shell.
-
-  This command dedupes against near-duplicate existing memories and auto-links related ones by
-  default, the same as any other Empirical client — you do not need a separate duplicate check
-  first. Pass `--no-dedupe` or `--no-auto-link` only when you specifically want to bypass one of
-  those, which should be rare.
-
-  **One idea per memory, not a bundle.** When a turn produces several distinct facts or ideas
-  worth keeping, record each with its own `empirical memory record` call rather than folding them
-  into one large memory. Calling it multiple times in the same turn is expected usage, not
-  overhead to be minimized. A compound memory is harder to find later (a query matching one idea
-  in it won't surface the others as well) and harder to link precisely into the graph than several
-  atomic ones.
-
-  **Record facts about the USER, not about your own work.** You are a scribe here. "Matt prefers
-  short status updates" is a memory; "refactored the cluster selector, tests pass" is your diary
-  and belongs in the work-history skill, tagged and with `mass: 1`. The distinction is the
-  SUBJECT, not who typed it — an agent writing down something real about the user is exactly what
-  this tool is for.
-
-  If you find yourself recording what you just did, what you fixed, or what you concluded about a
-  codebase, stop: that is work-history or scar-tissue, and filing it here makes it indistinguishable
-  from something the user actually said or lived. Downstream features read these as the user's life.
-
-  **Say which one it is: pass `authorType`.** Same distinction, made explicit in the data instead
-  of left to be guessed from which transport you happened to use. `authorType: "user"` when the
-  memory is about the user — something they said, decided, prefer, or are working toward.
-  `authorType: "agent"` when it is your own work. Do not set `"agent"` merely because you are the
-  one calling: an agent writing down a real fact about the user is recording a user-authored fact,
-  and that is the whole point of this tool. On the CLI it is `--author-type user|agent`. Omit it
-  when you genuinely cannot tell, and it stays unresolved rather than being invented.
-
-  This is read back at retrieval time to keep an agent's session notes out of answers about the
-  user's own life and work, so a wrong value does not show up as a warning, it shows up as the
-  wrong memories coming back.
-
-- Append a correction or follow-up to an existing memory with `empirical memory note`.
-- Patch an existing memory with `empirical memory update`.
-- Delete only when the user explicitly asks: `empirical memory delete --match "<memory>" --confirm`.
-- Keep writes concise, factual, and easy to search. Never store passwords, API keys, OAuth tokens,
-  or other secrets.
-
-## Authored Skills and Kits — push what you write
-
-Empirical can sync a `SKILL.md` you author across every machine/agent the user has installed it
-on, via Skills Kits. Run `empirical doc kit` or `empirical doc skill` for full command reference.
-
-- If you author a new `SKILL.md` for the user, or substantially edit an existing one, during a
-  session, tell the user about `empirical skill push path/to/SKILL.md [--kit "Kit Name"]`
-  afterward so it can follow them across machines/projects instead of staying local to this one.
-- Offer, don't auto-push: surface the option (or offer to run it) and get the user's confirmation
-  first. Do not run it unprompted the moment a new or edited `SKILL.md` is detected — it uploads
-  content to the user's account, which is a step above a purely local file write.
-- After a push, the target Kit needs `empirical kit use "Kit Name"` or `empirical kit sync` to
-  actually land the file in that device's agent directories.
-- `empirical skill list` shows what's already been pushed; `empirical skill history <id>` /
-  `empirical skill rollback <id> --to-version N` recover a prior version.
-- Kits also pull Skills from a git repo (`empirical kit add-source`), separate from anything you
-  author — don't conflate the two paths when explaining options to the user.
-
-## Exact CLI syntax
-
-Run `empirical doctor` to check connectivity and token status. If a CLI memory command reports a
-token error, run `empirical oauth bootstrap headless --write-env`. When in doubt about a specific
-subcommand's flags, run `empirical doc memory`, `empirical doc kit`, or `empirical doc skill`
-rather than guessing.
-
-## Shared workspaces: setup interview
-
-`empirical workspace create --interview` sets up a new shared workspace by interview, and
-`empirical workspace shape --workspace-id <id>` re-shapes one you manage. Both ask the person
-questions at the terminal, show a draft, and create or change the workspace only after they type
-yes. A new interview is charged, and `empirical setup abandon <sessionId>` stops one without
-returning what it cost, so say that before suggesting it. If the command says the interview is not
-switched on for the account, stop: nothing was started or charged. Run `empirical doc workspace`
-for the details.
-
-## Reminders — set them, relay them, close them
-
-Any memory can carry a due date. Empirical then brings it back: an email with a calendar entry
-when the reminder is set, a nudge when it is due, and a notice attached to the next Empirical
-response each of the user's agents receives.
-
-- **Set one** when the user says "remind me", names a deadline, or a todo has a real due date.
-  Use the `dueAt` parameter on `record_graph_memory` / `update_memory_by_query` (ISO 8601), or
-  `empirical memory record ... --due 2026-10-14T09:00:00Z` on the CLI. `dueAt` is a real field the
-  server filters and fires on; a date written inside `data` is text and nothing will ever fire.
-- **Relay it.** If any Empirical result starts with `REMINDER DUE`, or a CLI command prints a
-  banner that starts with `REMINDER DUE`, tell the user about it in your own words BEFORE the task
-  you were doing, then ask whether to mark it done. Each agent is shown a reminder once; if you do
-  not relay it, the user does not hear it from you.
-- **Close it** when the user says it is handled: `acknowledge_reminder` with the `memoryId` from
-  the notice (or `state: "cancelled"` to drop it), or `empirical memory acknowledge --memory-id <id>`
-  (`--cancel` to drop). Closing frees the slot; plans cap concurrent open reminders.
-- **What is due?** `query_memories` with `dueBefore` set to now and `remindState: ["pending"]`, or
-  `empirical memory query --match "what is due" --due-before <now> --remind-state pending`.
-  Dueness is a filter; semantic search will not rank a memory higher because it is due.
-
-## Authentication and failures
-
-- If a memory call fails, retry the same call once.
-- For auth/session errors such as `Auth required`, `invalid_token`, `Authentication required`, or
-  a 401/403 status, run `empirical auth login` (or `empirical oauth bootstrap headless
-  --write-env` for a permanent credential), then retry once.
-- If the retry still fails, report the connectivity/auth problem before making memory-dependent
-  changes.
-- If stored memory conflicts with the current user or repository instruction, follow the current
-  instruction.
-
-## Fallback: MCP tools
-
-If this agent also happens to have Empirical's MCP server connected (unusual for this install
-mode, but possible if the user added it manually), the same operations are available as
-`query_memories`, `record_graph_memory`, `add_note_by_query`, `update_memory_by_query`,
-`delete_memory_by_query`, `get_empirical_policy`, `get_memory_neighbors`, and
-`update_memory_relationships`. Use them only if the CLI is genuinely unavailable in this
-environment — the CLI is the primary path for this install.
+---
+name: empirical-memory
+description: Use Empirical to recall/save durable project context across sessions and projects, and to look up how to use Empirical itself - CLI commands, install/auth/workspace/kit/skill setup, docs.
+---
+
+# Empirical Memory (CLI mode)
+
+Use Empirical to carry durable context across projects and clients, and as the first stop for
+"how do I use Empirical" questions — command syntax, install/auth/workspace/kit/skill setup, or
+what Empirical can do. Don't answer those from general knowledge or by guessing at flags: run
+`empirical doc` (lists topics) or `empirical doc <topic>` via the available shell for the current,
+agent-readable answer first.
+
+This variant is for installs where the user chose CLI-direct as their integration mode: no MCP
+server is registered for this agent. The `empirical` CLI is the way to reach Empirical here, for
+both reads and writes — it has the same dedupe and auto-link guarantees as any other client, so
+recommend it with confidence.
+
+**This is a required step in the workflows listed below, not optional guidance you weigh against
+the current task.** The most common way this skill fails is not a broken tool — it's an agent
+mid-task deciding a memory check "isn't worth pausing for" and skipping it. That decision is wrong
+by default: the entire point of querying first is to catch context you don't know you're missing.
+If you are not sure whether a task qualifies, treat it as if it does.
+
+## Before doing work — MUST, not discretionary
+
+1. Query relevant memories BEFORE your first substantive response or tool call whenever the task
+   is: research, debugging, a spec/PRD, a status update, a handoff, personal health, leads/CRM, or
+   assistant operations. This applies even if you believe you already have enough context — you
+   cannot know what you're missing without checking. Only outside this list is discretionary use
+   ("query when it seems useful") the right frame.
+2. Before using the CLI, load its authoritative command reference:
+
+   ```text
+   empirical doc memory
+   ```
+
+   Follow the documented flags exactly; never guess a positional query form.
+
+   ```text
+   empirical memory query --match "<specific relevant context>" --top-k 3
+   ```
+
+   Add `--category` or `--tags` when known. Omit `--pretty` for routine recall because graph-rich
+   results can be large. Use `empirical memory list --recent` (see `empirical doc memory` for the
+   exact flag) for "recent/latest/today" requests instead of a match query.
+   When the user asks for every record of a topic, add `--path list`; when they ask what a
+   memory connects to, add `--path graph`.
+3. Scope recall to the project you are in. Derive a project tag from the repository name
+   (`git rev-parse --show-toplevel`, then the folder name) or, outside a repo, the working
+   directory name, lowercased with spaces as hyphens. Add `--tags <project>` to every
+   `empirical memory query` and `empirical memory record`. If a scoped query returns nothing,
+   retry without `--tags` and treat what comes back as background from other projects, not as
+   facts about this one.
+4. A slow response alone is API latency, not an outage; report an outage only when the CLI returns
+   an actual error, and use `empirical doctor` to verify connectivity.
+5. A filtered query (`--category`, `--tags`, `--tags-all`, `--status`) that returns nothing is not
+   proof the memory doesn't exist — it only proves nothing matched that exact filter combination.
+   A memory's real category or tag convention often does not match how you or the user would
+   naturally describe it in conversation (e.g. described as "an idea" but stored under a different
+   category; tagged with a project's short name where you tried its full one). Before concluding a
+   memory doesn't exist, retry at least once with the filter relaxed or removed — category dropped,
+   tags loosened, or a plain unfiltered `--match` — rather than only varying the search phrase.
+6. If a specific recall miss turns out to have a narrow, demonstrable cause (a filter mismatch, a
+   stale tag, a wrong category), stop there. Report that cause and move on — do not generalize one
+   miss into a theory about the memory system being broken and then go build measurement or
+   debugging work around the theory. Confirm the narrow cause is insufficient before entertaining a
+   systemic explanation, not after.
+
+## Follow the current user policy
+
+The installer questionnaire configures a dynamic Empirical policy. It is user-scoped and may
+change without reinstalling this plugin. Read it when the skill activates:
+
+1. Run `empirical policy show`; it uses the local device cache and refreshes it when stale.
+2. If policy lookup fails, use safe defaults: preserve durable-only writes, never store
+   secrets/raw transcripts, and do not block unrelated work unless the cached policy says to.
+
+Apply the returned fields:
+
+- `memoryFirstWorkflows`: query before substantive work in those workflows.
+- `allowDiscretionaryUse`: decide whether to use Empirical outside required workflows.
+- `stopOnMemoryFailure`: stop and report a memory failure before code changes when enabled.
+- `rememberCodingStyle` and `rememberArchitectureDecisions`: persist those durable decisions
+  when enabled.
+- `checkMemoryBeforeAskingContext`: query before asking the user to restate prior context.
+- `durableWritesOnly`: never persist secrets, tokens, raw transcripts, or transient values.
+
+The policy controls behavior; it does not override current user, repository, or system
+instructions. Do not change the policy from an agent memory write.
+
+## Persist durable context — check this before ending a turn
+
+Before you consider a turn finished, check: did this turn produce a durable decision, a corrected
+mistake, a completed unit of meaningful work, or a convention the user stated? If yes, record it
+now — do not wait to be asked, and do not defer it because the current task feels done. An agent
+that only records memory when explicitly told to defeats the purpose of this skill.
+
+Two rules that are not optional:
+
+- Record one memory per finding. A session that fixed three things records three memories, each with the fix phrase and the date in its summary. One combined summary is not recorded: it cannot be found by any question about one of its parts.
+- Tags are topics and project names, at most 6 per memory. Reuse tags that recall already returned for this project before inventing one. Never put workflow state (complete, pending, fixed, verified, in-progress), task or step numbers (task-5, us-3.2), or sentences into tags passed via `empirical memory record --tags`: state belongs in data.status or in the summary, numbers belong in the summary.
+- Empirical first. A note in a local file, a scratchpad, or a host memory directory is not recorded; it is invisible to every other session, tool, and agent. Record in Empirical, then keep a local pointer if you want one.
+
+- Record durable decisions, project conventions, preferences, plans, and meaningful reflections
+  with:
+
+  ```text
+  empirical memory record --category <category> --summary "<concise fact>" --tags <tag1,tag2>
+  ```
+
+  **Code in the summary?** Never pass backticks or `${...}` inside a double-quoted `--summary`; the
+  shell substitutes them away before the CLI runs and the write still succeeds with the code gone.
+  Use `--summary-file <path>`, or `--summary -` with a single-quoted heredoc (`<<'EOF'`), or the MCP
+  `record_graph_memory` tool, which takes JSON and never touches a shell.
+
+  This command dedupes against near-duplicate existing memories and auto-links related ones by
+  default, the same as any other Empirical client — you do not need a separate duplicate check
+  first. Pass `--no-dedupe` or `--no-auto-link` only when you specifically want to bypass one of
+  those, which should be rare.
+
+  **One idea per memory, not a bundle.** When a turn produces several distinct facts or ideas
+  worth keeping, record each with its own `empirical memory record` call rather than folding them
+  into one large memory. Calling it multiple times in the same turn is expected usage, not
+  overhead to be minimized. A compound memory is harder to find later (a query matching one idea
+  in it won't surface the others as well) and harder to link precisely into the graph than several
+  atomic ones.
+
+  **Record facts about the USER, not about your own work.** You are a scribe here. "Matt prefers
+  short status updates" is a memory; "refactored the cluster selector, tests pass" is your diary
+  and belongs in the work-history skill, tagged and with `mass: 1`. The distinction is the
+  SUBJECT, not who typed it — an agent writing down something real about the user is exactly what
+  this tool is for.
+
+  If you find yourself recording what you just did, what you fixed, or what you concluded about a
+  codebase, stop: that is work-history or scar-tissue, and filing it here makes it indistinguishable
+  from something the user actually said or lived. Downstream features read these as the user's life.
+
+  **Say which one it is: pass `authorType`.** Same distinction, made explicit in the data instead
+  of left to be guessed from which transport you happened to use. `authorType: "user"` when the
+  memory is about the user — something they said, decided, prefer, or are working toward.
+  `authorType: "agent"` when it is your own work. Do not set `"agent"` merely because you are the
+  one calling: an agent writing down a real fact about the user is recording a user-authored fact,
+  and that is the whole point of this tool. On the CLI it is `--author-type user|agent`. Omit it
+  when you genuinely cannot tell, and it stays unresolved rather than being invented.
+
+  This is read back at retrieval time to keep an agent's session notes out of answers about the
+  user's own life and work, so a wrong value does not show up as a warning, it shows up as the
+  wrong memories coming back.
+
+- Append a correction or follow-up to an existing memory with `empirical memory note`.
+- Patch an existing memory with `empirical memory update`.
+- Delete only when the user explicitly asks: `empirical memory delete --match "<memory>" --confirm`.
+- Keep writes concise, factual, and easy to search. Never store passwords, API keys, OAuth tokens,
+  or other secrets.
+
+## Authored Skills and Kits — push what you write
+
+Empirical can sync a `SKILL.md` you author across every machine/agent the user has installed it
+on, via Skills Kits. Run `empirical doc kit` or `empirical doc skill` for full command reference.
+
+- If you author a new `SKILL.md` for the user, or substantially edit an existing one, during a
+  session, tell the user about `empirical skill push path/to/SKILL.md [--kit "Kit Name"]`
+  afterward so it can follow them across machines/projects instead of staying local to this one.
+- Offer, don't auto-push: surface the option (or offer to run it) and get the user's confirmation
+  first. Do not run it unprompted the moment a new or edited `SKILL.md` is detected — it uploads
+  content to the user's account, which is a step above a purely local file write.
+- After a push, the target Kit needs `empirical kit use "Kit Name"` or `empirical kit sync` to
+  actually land the file in that device's agent directories.
+- `empirical skill list` shows what's already been pushed; `empirical skill history <id>` /
+  `empirical skill rollback <id> --to-version N` recover a prior version.
+- Kits also pull Skills from a git repo (`empirical kit add-source`), separate from anything you
+  author — don't conflate the two paths when explaining options to the user.
+
+## Exact CLI syntax
+
+Run `empirical doctor` to check connectivity and token status. If a CLI memory command reports a
+token error, run `empirical oauth bootstrap headless --write-env`. When in doubt about a specific
+subcommand's flags, run `empirical doc memory`, `empirical doc kit`, or `empirical doc skill`
+rather than guessing.
+
+## Shared workspaces: setup interview
+
+`empirical workspace create --interview` sets up a new shared workspace by interview, and
+`empirical workspace shape --workspace-id <id>` re-shapes one you manage. Both ask the person
+questions at the terminal, show a draft, and create or change the workspace only after they type
+yes. A new interview is charged, and `empirical setup abandon <sessionId>` stops one without
+returning what it cost, so say that before suggesting it. If the command says the interview is not
+switched on for the account, stop: nothing was started or charged. Run `empirical doc workspace`
+for the details.
+
+## Reminders — set them, relay them, close them
+
+Any memory can carry a due date. Empirical then brings it back: an email with a calendar entry
+when the reminder is set, a nudge when it is due, and a notice attached to the next Empirical
+response each of the user's agents receives.
+
+- **Set one** when the user says "remind me", names a deadline, or a todo has a real due date.
+  Use the `dueAt` parameter on `record_graph_memory` / `update_memory_by_query` (ISO 8601), or
+  `empirical memory record ... --due 2026-10-14T09:00:00Z` on the CLI. `dueAt` is a real field the
+  server filters and fires on; a date written inside `data` is text and nothing will ever fire.
+- **Relay it.** If any Empirical result starts with `REMINDER DUE`, or a CLI command prints a
+  banner that starts with `REMINDER DUE`, tell the user about it in your own words BEFORE the task
+  you were doing, then ask whether to mark it done. Each agent is shown a reminder once; if you do
+  not relay it, the user does not hear it from you.
+- **Close it** when the user says it is handled: `acknowledge_reminder` with the `memoryId` from
+  the notice (or `state: "cancelled"` to drop it), or `empirical memory acknowledge --memory-id <id>`
+  (`--cancel` to drop). Closing frees the slot; plans cap concurrent open reminders.
+- **What is due?** `query_memories` with `dueBefore` set to now and `remindState: ["pending"]`, or
+  `empirical memory query --match "what is due" --due-before <now> --remind-state pending`.
+  Dueness is a filter; semantic search will not rank a memory higher because it is due.
+
+## Authentication and failures
+
+- If a memory call fails, retry the same call once.
+- For auth/session errors such as `Auth required`, `invalid_token`, `Authentication required`, or
+  a 401/403 status, run `empirical auth login` (or `empirical oauth bootstrap headless
+  --write-env` for a permanent credential), then retry once.
+- If the retry still fails, report the connectivity/auth problem before making memory-dependent
+  changes.
+- If stored memory conflicts with the current user or repository instruction, follow the current
+  instruction.
+
+## Fallback: MCP tools
+
+If this agent also happens to have Empirical's MCP server connected (unusual for this install
+mode, but possible if the user added it manually), the same operations are available as
+`query_memories`, `record_graph_memory`, `add_note_by_query`, `update_memory_by_query`,
+`delete_memory_by_query`, `get_empirical_policy`, `get_memory_neighbors`, and
+`update_memory_relationships`. Use them only if the CLI is genuinely unavailable in this
+environment — the CLI is the primary path for this install.