superlocalmemory 4.1.21 → 4.1.23

package/plugin/skills/slm-governance/SKILL.md

@@ -1,236 +1,208 @@
 ---
 name: slm-governance
-description: Enterprise compliance and governed workspace behavior for SuperLocalMemory. Covers role-based access (admin/member/viewer), retention policies, audit trail, GDPR data export/erase, and how agents must behave when operating under workspace governance. Requires power MCP profile for audit/retention tools. Agents must never bypass governance controls.
+description: Governed-workspace behavior for SuperLocalMemory. Covers roles (admin/member/viewer) and company mode, retention and lifecycle settings, the audit trail, GDPR export and erasure, and how agents must behave when operating under workspace governance. The audit and retention tools need the power MCP profile. Agents must never bypass governance controls.
 when_to_use: |
   - "What can I do in this workspace?" (role check)
-  - "Set a 90-day retention policy on this memory"
+  - "Move cold memories to archive after 60 days"
   - "Show the audit trail for recent memory operations"
   - "Export my data for GDPR compliance"
-  - "Delete all memories for user X (right to erasure)"
-  - "Configure require-login for this workspace"
+  - "Delete all memories about user X (right to erasure)"
+  - "Turn on require-login for this workspace"
   - Enterprise deployment with multi-team shared SLM
   - Compliance, audit, or data governance task
-allowed-tools: audit_trail, set_retention_policy, get_retention_stats, get_lifecycle_status, recall, search, remember, Bash
+allowed-tools: audit_trail, set_retention_policy, get_retention_stats, get_lifecycle_status, compact_memories, consistency_check, recall, search, remember, Bash
 ---
 
-# slm-governance — Enterprise Compliance and Governed Workspace Behavior
+# slm-governance — Governed Workspace Behavior
 
-SuperLocalMemory supports enterprise deployments with role-based access control,
-retention policies, audit logging, and GDPR compliance tooling. This skill
-documents how agents must behave when operating in a governed workspace and how
-to use the governance MCP tools (available in the `power` profile).
+SuperLocalMemory can run with named users and roles per workspace (company
+mode), keeps a compliance audit trail, applies a retention lifecycle, and ships
+GDPR export and erasure commands. This skill documents how an agent must behave
+in a governed workspace and what the governance tools really do. The MCP audit
+and retention tools are in the `power` tool set (see `slm-profile`).
 
 ---
 
 ## Role model
 
-Governed workspaces have three roles:
+By default SLM is single-user: whoever runs it is the owner and nothing asks for
+a login. Company mode adds named users, each with one role per workspace
+(profile). A role in one workspace grants nothing in another.
 
-| Role | Read | Write personal | Write shared/global | Admin operations |
-|------|------|---------------|---------------------|-----------------|
-| `viewer` | Yes | No | No | No |
-| `member` | Yes | Yes | Yes (within access list) | No |
-| `admin` | Yes | Yes | Yes (unrestricted) | Yes |
+| Role | Read | Write | Share (`shared`/`global` writes) | Delete | Manage users and settings |
+|------|------|-------|-------|--------|-----------------|
+| `viewer` | Yes | No | No | No | No |
+| `member` | Yes | Yes | Yes | No | No |
+| `admin` | Yes | Yes | Yes | Yes | Yes |
 
 **Agent behavior by role:**
 
-- **Viewer**: Only call `recall`, `search`, `fetch`, `list_recent`. Never call
-  `remember`, `update_memory`, `forget`, or any write tool. If a write is
-  attempted, fail gracefully: "This workspace is read-only in viewer mode."
-- **Member**: May write personal facts and shared facts with permitted profiles.
-  May NOT write `scope="global"` facts without explicit admin authorization.
-  May NOT call `set_retention_policy`, `audit_trail`, or `compact_memories`.
-- **Admin**: Full access including governance tools in the `power` profile.
+- **Viewer**: Only call `recall`, `search`, `fetch`, `list_recent` and other
+  reads. Never call `remember`, `update_memory`, `delete_memory` or any write
+  tool. If a write is refused, say so: "This workspace is read-only for my role."
+- **Member**: May write memories, including `scope="shared"` and `scope="global"`
+  when the user explicitly asks for them. May not delete memories or change
+  users, roles or settings.
+- **Admin**: Everything above plus deletion and user administration.
 
-An agent operating in a governed workspace must check its role before any write
-operation. Role information is visible in workspace configuration or via
-`slm status --json` (the `role` field, if present).
+No MCP tool or `slm` command reports your role (only a signed-in dashboard session can ask the daemon, at `GET /api/rbac/whoami`). Do not guess it: attempt
+what the user asked and treat a permission refusal as final. Setting up users,
+roles and "Require login" is done in the dashboard under **Settings → Access**;
+there is no `slm user` or `slm role` command. The machine operator keeps user
+administration in every mode so a mistake cannot lock everyone out.
 
 ---
 
-## Retention policies
+## require-login
 
-Retention policies control how long facts are stored before they become eligible
-for decay. Available in the `power` MCP profile.
+When login is required, every operation on memories needs a signed-in user,
+including the connection your assistant uses. SLM handles this at the daemon
+level; agents do not pass credentials in tool calls. If a tool call returns an
+authentication or permission error, you must:
 
-### Set a retention policy
+1. Stop the current operation immediately.
+2. Report the requirement to the user.
+3. Never cache, retry, or work around the block.
 
-```
-set_retention_policy(
-  profile_id: str = "",   # "" = active profile
-  days: int = 90,         # facts older than this become decay-eligible
-  zone: str = "default",  # retention zone name
-)
-```
+In this mode, `include_global=True` and `include_shared=True` on `recall` are
+quietly turned off while the recall policy forbids cross-profile reads (the
+default), so an opt-in recall can come back with only personal facts. Do not try
+to work around it. See `slm-scope`.
 
-Retention zones let you apply different policies to different fact categories:
+---
 
-```
-# Standard facts: 90-day retention
-set_retention_policy(profile_id="", days=90, zone="default")
+## Retention and lifecycle
 
-# Security findings: 365-day retention (compliance requirement)
-set_retention_policy(profile_id="", days=365, zone="security")
-```
+Every memory moves through lifecycle states as it goes unused: active, warm, cold,
+archived. Two tools set and inspect that, and a third runs the forgetting cycle.
+They need the `power` tool set.
+
+### Set the thresholds
 
-Tag your facts with the zone name to route them to the right policy:
 ```
-remember(content="Critical auth bypass in v2.1", tags="security,cve,finding", ...)
+set_retention_policy(
+  cold_after_days: int = 30,      # days of inactivity before a memory goes cold
+  archive_after_days: int = 90,   # days before it is archived
+)
 ```
 
-### Check retention statistics
+It sets two thresholds and returns them. There is no `profile_id` argument and
+there are no named retention zones or per-tag policies; tagging a memory does not
+route it to a different policy.
+
+### Look at the state
 
 ```
-get_retention_stats()
+get_retention_stats(profile_id="")
+get_lifecycle_status(limit=50, profile_id="")
 ```
 
-Returns zone distribution, average fact age, and decay-eligible counts. Use this
-to verify policies are working as expected.
+`get_retention_stats` reports, from the retention table, the count and average
+retention score per Ebbinghaus zone (`active`, `warm`, `cold`, `archive`,
+`forgotten`) and the totals. `get_lifecycle_status` counts the active, warm, cold
+and archived state of up to `limit` memories and returns up to ten short
+samples of each. Neither says when the next cycle runs.
 
-### Check lifecycle status
+### Apply it
 
 ```
-get_lifecycle_status()
+forget(dry_run=True)          # preview the decay cycle for the active profile
+compact_memories(dry_run=True) # preview lifecycle-state transitions
 ```
 
-Reports the state of the retention and decay subsystem — whether decay cycles are
-running, when the next cycle runs, and any backlog.
+The MCP `forget` tool is not a delete: it recomputes retention scores and moves
+memories between zones. `compact_memories` moves memories whose lifecycle state
+has become due (for example cold to archived); it does not merge duplicates. Both
+default to a dry run. Run the preview first, show it to the user, and only then
+pass `dry_run=False`. Do not run either without the user's say-so.
 
 ---
 
 ## Audit trail
 
-`audit_trail` is available in the `power` profile. It returns a structured log of
-recent memory operations (writes, reads, profile switches, policy changes).
-
 ```
-audit_trail(
-  limit: int = 50,          # number of entries to return
-  operation: str = "",      # filter by operation type (e.g. "remember", "forget")
-  profile_id: str = "",     # filter by profile; "" = active profile
-)
+audit_trail(limit: int = 50)
 ```
 
-Use this for:
-- Compliance reviews ("what data was written in the last 30 days?")
-- Investigating unexpected memory changes
-- Generating audit reports for data controllers
+Returns the newest `limit` rows of the compliance audit for the active profile,
+as `{"success", "entries", "count"}`. Each entry has `audit_id`, `profile_id`,
+`action`, `target_type`, `target_id`, `details` and `timestamp`. There are no
+filter arguments. Entries are compliance actions (store, retrieve, delete, export
+and the like).
 
-The audit trail covers MCP and CLI operations. It does not record the content of
-facts by default — only operation type, timestamp, agent ID, and fact ID.
+Use it for compliance reviews, for investigating an unexpected change, and for
+audit reports to a data controller.
 
 ---
 
-## GDPR compliance
-
-### Data export
-
-SLM does not have a dedicated MCP export tool. For GDPR data subject access
-requests, use the CLI:
+## GDPR
 
 ```bash
-# Export all memories in a profile to JSON
-slm status --json     # confirm active profile
-slm list --limit 9999 --json > export.json
+slm gdpr status [--profile P] [--json]            # posture: receipts, audit counts, known gaps; read-only
+slm gdpr export --profile P [--output FILE] [--json]   # Art. 15/20 access and portability
+slm gdpr erase --profile P --dry-run [--json]     # preview an erasure
+slm gdpr erase --profile P --yes [--json]         # Art. 17 erasure, IRREVERSIBLE
+slm gdpr verify --receipt-id ID [--profile P]     # check an erasure receipt (exit 0 ok, 1 tampered, 2 not found)
 ```
 
-For a complete export including entity graph data, run:
-```bash
-slm status --json
-```
-
-Contact your workspace admin to arrange a full database-level export if the CLI
-output is insufficient for compliance purposes.
-
-### Right to erasure
+`slm gdpr erase` erases a **profile**. It refuses to run without both `--profile`
+and `--yes`, and without them it only previews. It is the only irreversible
+operation here, so confirm the subject, the profile and the authority to erase
+with the user before running it. `slm gdpr status` lists the known gaps (for
+example backups and the code graph) rather than claiming completeness.
 
-To erase all memories for a subject or project:
+To remove individual memories rather than a whole profile, use the deletion
+commands from `slm-remember`:
 
 ```bash
-# Step 1: preview what will be deleted (ALWAYS do this first)
-slm forget "<subject or project name>" --dry-run --json
-
-# Step 2: review the preview, then execute
+slm forget "<subject or project name>" --dry-run --json   # ALWAYS first
 slm forget "<subject or project name>" --yes --json
-```
-
-For targeted deletion by fact ID:
-```bash
 slm delete <fact_id> --yes --json
 ```
 
-For data reconstruction prevention: after erasure, confirm the fact is gone by
-running `slm recall "<content>"`. A successful erasure returns no results. Never
-attempt to re-derive erased content from other stored facts.
-
----
-
-## require-login
-
-When `require_login` is enabled in workspace configuration, agents must
-authenticate before any memory operation. SLM handles authentication at the
-daemon level — agents do not need to pass credentials in tool calls. If an
-agent receives an authentication error from any MCP tool, it must:
-
-1. Stop the current operation immediately.
-2. Report the authentication requirement to the user.
-3. Never cache, retry, or work around the authentication block.
+Memories that belong to a reviewed correction cannot be deleted this way; the
+refusal names the case. After an erasure, confirm with `slm recall "<content>"`
+that nothing comes back, and never try to re-derive erased content from other
+stored facts.
 
 ---
 
 ## Scope enforcement in governed workspaces
 
-In a governed workspace, scope restrictions are enforced server-side:
-- **Viewers** cannot write any fact regardless of `scope` parameter.
-- **Members** cannot write `scope="global"` unless their access list includes
-  the global scope — attempts return a permission error.
-- **Admins** can write any scope.
-
-Agents must not attempt to work around scope restrictions by splitting a global
-fact into multiple shared facts to accumulate equivalent visibility.
-
----
-
-## Compact memories (admin-only)
-
-`compact_memories` deduplicates and consolidates stored memories. This is an
-admin operation — it can change fact IDs and remove content.
-
-```
-compact_memories(
-  profile_id: str = "",   # "" = active profile
-  dry_run: bool = True,   # ALWAYS true first — inspect before running
-)
-```
-
-Always run with `dry_run=True` first and review the impact report. Never run
-compaction without admin authorization.
+- **Viewers** cannot write anything, whatever the `scope` argument.
+- **Members and admins** can write `shared` and `global` facts; writing either
+  scope needs the share permission, which both roles hold.
+- Agents must not split a `global` fact into several `shared` facts, or otherwise
+  accumulate visibility the user did not ask for.
 
 ---
 
-## Consistency check (admin-only)
+## Integrity checks
 
 ```
-consistency_check(profile_id: str = "")
+consistency_check(limit: int = 100)
 ```
 
-Verifies data integrity of the memory store — checks for orphaned entities,
-broken references, and index-database mismatches. Use after migrations or
-unexpected shutdowns. Returns a structured report.
+Runs a sheaf-consistency check over up to `limit` memories and returns pairs of
+facts that contradict each other, with a severity (`fact_a`, `fact_b`,
+`severity`, `content_a`), plus `facts_checked`, `facts_errored` and
+`total_contradictions`. If the checker is disabled it says so in `note`. For the
+health of the store itself (orphan rows, erased words left behind, unfinished
+deletes) use `slm db integrity` and `slm db repair`; see `slm-status`.
 
 ---
 
 ## Agent checklist for governed workspaces
 
 Before each write operation:
-- [ ] Confirm my role allows writes (viewer → skip; member/admin → proceed)
-- [ ] Confirm scope is appropriate for my role (member → no global)
-- [ ] Set correct tags including zone name if retention policy applies
-- [ ] Pass `session_id` for full audit attribution
-
-Before running any destructive operation (`forget`, `compact_memories`):
-- [ ] Admin authorization confirmed
-- [ ] Ran with `dry_run=True` and reviewed output
+- [ ] The user asked for it, and a refusal from the workspace is respected
+- [ ] Scope is `personal` unless the user explicitly asked to share
+- [ ] Pass `session_id` so the write is attributed
+
+Before running any destructive or state-changing operation (`forget`,
+`compact_memories`, `slm forget --yes`, `slm gdpr erase --yes`):
+- [ ] The user authorized it in this conversation
+- [ ] Ran the dry run or preview and showed it to the user
 - [ ] GDPR: confirmed the subject or controller authorized the erasure
 
 ---
@@ -238,11 +210,12 @@ Before running any destructive operation (`forget`, `compact_memories`):
 ## Related skills
 
 - `slm-scope` — scope model details (personal/shared/global)
-- `slm-profile` — workspace isolation and profile switching
-- `slm-remember` — fact storage reference (includes scope parameters)
+- `slm-profile` — memory profiles and tool sets
+- `slm-remember` — fact storage, corrections and deletion
 - `slm-recall` — retrieval reference (includes scope read flags)
-- `slm-mesh` — mesh tools (full/power profiles)
+- `slm-mesh` — mesh tools
+- To use this memory from a web assistant or another computer, see the slm-web-access skill.
 
 ---
 
-*SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-graph/SKILL.md

@@ -20,7 +20,7 @@ allowed-tools: build_code_graph, query_graph, get_blast_radius, semantic_search_
 
 # slm-graph — Code Intelligence Skill
 
-Index any repo as a code knowledge graph and answer structural questions about it: callers, callees, impact radius, semantic search, and review context. Requires the `code` MCP profile (set `SLM_MCP_PROFILE=code` in your plugin `.mcp.json`).
+Index any repo as a code knowledge graph and answer structural questions about it: callers, callees, impact radius, semantic search, and review context. These tools are only registered in the `code` MCP tool set (or with `SLM_MCP_ALL_TOOLS=1`); see "Tool set requirement" below.
 
 **Prerequisite rule:** every tool except `build_code_graph` self-guards — if the graph is not built it returns `{"success": false, "error": "Code graph not built. Run build_code_graph first."}`. Always index first.
 
@@ -40,7 +40,7 @@ build_code_graph(
 
 Parses all supported source files, extracts functions/classes/imports, builds the call graph, detects execution flows, and identifies code communities. Replaces any previous index for the same repo.
 
-- `repo_path` — absolute path to the repository root. Must exist.
+- `repo_path` — absolute path to the repository root. Must exist and sit under your home directory; a path outside it is refused with `Invalid repo_path`.
 - `languages` — comma-separated language filter, e.g. `"python,typescript"`. Empty string = index all supported languages.
 - `exclude_patterns` — comma-separated glob patterns to exclude, e.g. `"**/node_modules/**,**/.venv/**"`. Empty = no exclusions.
 
@@ -204,14 +204,14 @@ detect_changes(
 
 Runs `git diff` against `base`, maps the changed hunks to graph nodes, and returns a risk-scored list of changed functions, test gaps, and review priorities. Requires the repo to be a git repository.
 
-- `base` — git ref to diff against. Default `"HEAD~1"` (one commit back). Any valid git ref works: `"main"`, `"v3.6.13"`, a commit SHA, etc.
+- `base` — git ref to diff against. Default `"HEAD~1"` (one commit back). Any valid git ref works: `"main"`, `"v1.4.0"`, a commit SHA, etc.
 
 ```
 # What changed in the last commit?
 detect_changes()
 
 # What changed since the release branch?
-detect_changes(base="release/v3.6.13")
+detect_changes(base="release/1.4")
 
 # What changed relative to main?
 detect_changes(base="main")
@@ -277,16 +277,22 @@ All tools return `{"success": false, "error": "<message>"}` on failure — they
 | `Repository path does not exist: <path>` | Bad `repo_path` in build | Pass an absolute path that exists |
 | `Git not available or not a git repository: ...` | `detect_changes` needs git | Only works in git repos with git installed |
 | `Invalid pattern '...'` | Wrong `pattern` in `query_graph` | Use one of the 8 valid pattern strings |
-| `No node found matching '<target>'` | Target not in index | Rebuild or check the qualified name via `semantic_search_code` |
+| `No node found matching '<target>'` | Target not in index. Returned as `success: true` with an empty `results` and this `message`, not as an error | Rebuild or check the qualified name via `semantic_search_code` |
+| `Invalid repo_path: ...` | `repo_path` is outside your home directory | Index a repository under your home directory |
 
 If `build_code_graph` returns `files_parsed: 0`, no supported source files were found — check `repo_path` and `exclude_patterns`.
 
 ---
 
-## Profile Requirement
+## Tool set requirement
 
-This skill uses graph tools that are only active under the `code` MCP profile
-(or `full` / `power`). Your plugin `.mcp.json` must include:
+The six tools above are registered only when the MCP server runs the `code` tool
+set, or with `SLM_MCP_ALL_TOOLS=1` / `SLM_MCP_PROFILE=whole`, or when
+`SLM_MCP_TOOLS` names them. They are **not** in `core`, `full`, `power` or the
+no-profile default that the Claude Code and Codex plugins use, so with those
+settings the tools simply do not exist and a call fails as an unknown tool. The
+tool set is read when the server starts: set it in the host's MCP config and
+restart the host.
 
 ```json
 "env": {
@@ -295,21 +301,27 @@ This skill uses graph tools that are only active under the `code` MCP profile
 }
 ```
 
-Without this, the six graph tools are not registered and will appear as unknown
-tools. Run `slm status` to confirm the active profile.
+`switch_profile` does not change the tool set; it changes the active memory
+profile. See `slm-profile`. The `code` set leaves out the mesh and several
+administration tools, so ask the user before changing their tool set.
 
-**Switching profiles at runtime (v3.8.0+):** Use `switch_profile("code")` via
-MCP to activate the code profile in a session that started with a different
-profile. See `slm-profile` for the full profile switching workflow.
+With `SLM_MCP_ALL_TOOLS=1` more graph tools appear: `update_code_graph` (refresh
+for `changed_files` without a full rebuild), `list_graph_stats`,
+`get_architecture_overview`, `list_communities`, `get_community`, `list_flows`,
+`get_flow`, `get_affected_flows`, `find_large_functions`, `enrich_blast_radius`,
+`refactor_preview`, and the code-to-memory tools `link_memory_to_code`,
+`code_memory_search`, `code_entity_history` and `code_stale_check`. The memory
+links need `"bridge_enabled": true` in `code_graph_config.json` and a rebuild.
+All are host-only: a remote caller cannot use them.
 
 ---
 
 ## Related skills
 
-- `slm-profile` — workspace isolation and profile switching (required for code tools)
+- `slm-profile` — memory profiles and the tool sets that decide which tools exist
 - `slm-recall` — retrieve architectural decisions before graph queries
 - `slm-status` — confirm the active profile and graph index health
 
 ---
 
-SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-loop/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: slm-loop
-description: Run gate-verified bounded loops with SuperLocalMemory as the durable ledger. Use when a task has a checkable acceptance condition (tests, schema, lint, reconciliation) and you must iterate until an INDEPENDENT gate passes — never stopping just because the agent believes it is done. `slm loop demo` runs a keyless convergence demo; `slm loop history` and `slm loop show <run_id>` inspect past runs whose every lap is persisted as queryable SLM memory (tag `loop:<name>`). Terminal statuses are DONE / HALT / PAUSE / KILLED / ERROR — report them exactly, never converting HALT/PAUSE/ERROR into success.
-when_to_use: "run a bounded loop, gate-verified task, iterate until tests pass, verify against an independent gate, don't trust the agent's own done claim, slm loop, convergence loop, loop until green, loop ledger, resume a loop"
-allowed-tools: Bash, recall
+description: Gate-verified bounded loops with SuperLocalMemory as the durable ledger. Use when a task has a checkable acceptance condition and you must iterate until an INDEPENDENT gate passes — never stopping because the agent believes it is done. `slm_loop_run` (MCP) waits, under hard bounds, for a recall gate to pass; `slm loop demo` shows the control flow keyless; `slm loop history` and `slm loop show <run_id>` (or `slm_loop_history` / `slm_loop_show`) inspect past runs, whose every lap is stored as queryable SLM memory (tag `loop:<name>`). Terminal statuses are DONE / HALT / PAUSE / KILLED / ERROR — report them exactly, never converting HALT/PAUSE/ERROR into success.
+when_to_use: "run a bounded loop, gate-verified task, iterate until tests pass, verify against an independent gate, don't trust the agent's own done claim, slm loop, convergence loop, loop until green, loop ledger, wait for another agent's result"
+allowed-tools: slm_loop_run, slm_loop_history, slm_loop_show, recall, Bash
 ---
 
 # slm-loop — Bounded, gate-verified agent loops
@@ -16,19 +16,71 @@ this skill: **the gate is the authority.**
 
 Use a bounded loop whenever the goal has a mechanical, checkable contract: a
 test suite, a JSON schema, a linter, a reconciliation rule, a citation checker,
-a security scan. When the goal is subjective, keep a human approval gate (see
-rungs below).
+a security scan. When the goal is subjective, keep a human approval gate.
+
+## What SLM runs, and what you run
+
+SLM's loop engine runs the laps, enforces the bounds, calls the gate and writes
+the ledger. It does **not** start your tests or linters: it carries no
+subprocess or sandbox machinery. What each surface gives you:
+
+| Surface | What it does |
+|---|---|
+| `slm_loop_run` (MCP) | A *watcher*: each lap is a recall of `gate_query`; the loop ends when a confident match appears, or a bound trips. Use it to wait for a verification or coordination memory another agent will write (for example "build passed"). |
+| `slm loop demo` (CLI) | A keyless convergence demo: a stub proposer, a deterministic gate that passes on lap 3, every lap recorded. Proves the engine and ledger work end to end. |
+| `slm loop history`, `slm loop show` / `slm_loop_history`, `slm_loop_show` | Read the ledger of past runs. |
+| `superlocalmemory.loops.run_bounded_loop` (Python) | The engine itself, for code that supplies its own runner and gate callables. |
+
+For a task whose gate is a command (`pytest -q`, a schema validation), you run
+that command yourself each lap with Bash and read its exit code; the discipline
+below still applies, but SLM is not recording those laps. For graph runs with
+receipts, use the separate Bounded Loops product; SLM can take a read-only
+snapshot of its finished runs with `observe_bounded_loop_evidence(workspace)`
+(an absolute path), which records observations only and never changes recall or
+ranking.
 
 ## What SLM adds
 
-Every lap is written to SuperLocalMemory as a durable, queryable memory (tagged
-`loop:<name>`, session `loop:<run_id>`). That makes a run:
+Every lap SLM runs is written as a durable, queryable memory (tagged `loop:<name>`,
+session `loop:<run_id>`). That makes a run:
 
-- **auditable** — inspect the decision + gate verdict + budget for each lap;
-- **resumable / historical** — a run's ledger survives across sessions;
+- **auditable** — inspect the decision, gate verdict and budget for each lap;
+- **historical** — a run's ledger survives across sessions;
 - **discoverable** — visible via `slm recall`, the dashboard, and any
   SLM-integrated tool, alongside everything else the agent remembers.
 
+## MCP: `slm_loop_run`
+
+```
+slm_loop_run(
+  name: str,                    # 1–128 chars; also the memory tag
+  gate_query: str,              # the recall the gate checks each lap (up to 2000 chars)
+  gate_min_score: float = 0.0,  # minimum top-result score to pass
+  max_iterations: int = 20,     # hard lap cap, 1–200
+  max_wallclock_s: float = 15.0,# hard time cap; 0 disables; never more than 120
+  poll_interval_s: float = 1.0, # wait between laps; at least 0.25
+  max_tokens: int = 0,          # optional token budget; 0 disables
+  no_progress_window: int = 0,  # halt after N no-change laps; leave 0 for a watcher
+  require_support: bool = False,# pass only if the answer check ran and judged it sufficient
+)
+```
+
+The call **blocks** until the gate passes or a bound trips, then returns
+`{ok, status, reason, passed, laps, run_id, ledger: [{lap, decision, passed, detail}]}`.
+The gate recalls at most three memories per lap and ignores the loop's own
+ledger entries, so only a memory written by someone else can satisfy it. A
+recall the answer check judged insufficient never passes, even with a high
+score; with `require_support=True` an unchecked recall (check off, busy,
+loading, out of time) does not pass either. When the answer check is on, each
+lap asks it once about those memories; with the online check that is a request
+to the provider and may be billed. `slm_loop_run` is not available to remote
+callers.
+
+```
+slm_loop_history(name, limit=20)   # runs recorded under a loop name
+slm_loop_show(run_id, limit=200)   # every lap of one run, in order
+```
+
 ## CLI
 
 ```bash
@@ -37,9 +89,7 @@ slm loop history [--name NAME] [--json]   # list recorded runs
 slm loop show <run_id> [--json]           # every lap of one run
 ```
 
-`slm loop demo` proposes a fix, checks it against a deterministic gate that
-passes on lap 3, and records the run — a zero-setup way to see the control flow
-and confirm the SLM-backed ledger works end to end.
+There is no `slm loop run`.
 
 ## The bounds
 
@@ -49,11 +99,14 @@ A loop runs inside a safety envelope. Any bound tripping ends the run with
 - **max_iterations** — a hard lap cap.
 - **no_progress_window** — consecutive no-change laps before halting a spinning
   agent.
-- **token budget / wall-clock** — cumulative ceilings.
-- **kill switch** — set `SLM_LOOP_KILL` to stop before the next lap.
+- **token budget / wall-clock** — cumulative ceilings, checked again after each
+  lap, so an overshooting lap halts even if its gate would pass.
+- **kill switch** — a non-empty `SLM_LOOP_KILL` in the loop's process
+  environment stops it before the next lap, with status `KILLED`.
 - **approval rung** — L1 (report), L2 (assisted, pauses for approval), L3
-  (unattended). L2/L3 require approval before a passing gate is accepted as
-  DONE unless approval is explicitly configured off.
+  (unattended). L2 and L3 require approval before a passing gate is accepted as
+  DONE unless approval is explicitly configured off. `slm_loop_run` and the demo
+  run at L1, so `PAUSE` arises only from code that sets a higher rung.
 
 ## Terminal statuses — report exactly
 
@@ -72,8 +125,8 @@ paused, name the approval needed; when errored, quote the short detail.
 ## Reporting workflow
 
 1. Run or resume the loop.
-2. Read back the ledger with `slm loop show <run_id>` (or `slm recall` on tag
-   `loop:<name>`).
+2. Read back the ledger with `slm_loop_show` or `slm loop show <run_id>` (or
+   `slm recall` on tag `loop:<name>`).
 3. Report the exact terminal status, the lap count, and the gate's final
    verdict. Include the `run_id` so the run can be re-inspected later.
 
@@ -91,9 +144,10 @@ paused, name the approval needed; when errored, quote the short detail.
 ## Related skills
 
 - `slm-status` — confirm SLM is healthy before relying on the ledger.
-- `slm-recall` — query a loop's laps directly (`loop:<name>` tag).
+- `slm-recall` — query a loop's laps directly (`loop:<name>` tag), and the
+  answer-check fields the recall gate depends on.
 - `slm-session` — session lifecycle around a longer loop run.
 
 ---
 
-SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later