recall-os 0.2.1 → 0.3.1

package/README.md

@@ -15,9 +15,9 @@ decisions, module ownership, testing and security expectations, AI agent rules
 **validates** that memory with `recall doctor`. Architecture-neutral. No network, no telemetry, no
 code generation.
 
-[Install](#install) · [Quickstart](#quickstart) · [Commands](#commands) ·
-[What Doctor Checks](#what-doctor-checks) · [Presets](#presets) · [Why I built this](PHILOSOPHY.md)
-· [Contributing](CONTRIBUTING.md)
+[Website](https://recall-os.pages.dev) · [Install](#install) · [Quickstart](#quickstart) ·
+[Commands](#commands) · [What Doctor Checks](#what-doctor-checks) · [Presets](#presets) ·
+[Why I built this](PHILOSOPHY.md) · [Contributing](CONTRIBUTING.md)
 
 ![Recall OS — guided memory creation, ADR acceptance, and the doctor gate](https://raw.githubusercontent.com/Karthick-Ramachandran/recall-os/main/docs/media/recall-demo.gif)
 
@@ -35,12 +35,21 @@ What must not drift?    What evidence proves this work is complete?
 When these questions live in the repository instead of a chat window, the repository can answer
 them.
 
+> **Not a vector memory engine.** Tools like supermemory or mem0 _retrieve_ information with
+> embeddings; Recall OS writes the **decisions** themselves — reviewable files, not vectors — and
+> checks they stay consistent. They're complementary, not competitors. →
+> [Why I built this](PHILOSOPHY.md)
+
 ## Why Recall OS
 
 - **Memory that outlives the conversation.** Decisions, constraints, and ownership are committed to
   the repo, not trapped in an agent's context window.
 - **A gate, not just docs.** `recall doctor` is deterministic and returns an exit code, so "is this
   work actually finished and consistent?" becomes a check you can run in a hook or CI.
+- **Decisions change safely.** When a decision changes, `recall adr supersede` records it (the old
+  ADR is marked superseded, the new one links back) and Doctor flags any memory still citing the old
+  one — so the trail stays auditable instead of silently contradicted. The generated agent rules
+  even carry the CLI commands inline, so your AI tool uses them itself.
 - **Architecture-neutral by design.** Recall OS records and protects _your_ decisions. It never
   silently picks a framework, database, or pattern for you.
 - **Local-first and private.** No network calls, no telemetry, no AI API calls, no remote templates.
@@ -50,17 +59,19 @@ them.
 
 ## Install
 
-Install the CLI globally from npm:
+Run it without installing — the quickest way to try it:
 
 ```bash
-npm install -g recall-os
-recall --help
+npx recall-os@latest init
 ```
 
-Or run it without installing:
+Every command works the same way: `npx recall-os <command>` (e.g. `npx recall-os doctor`).
+
+Or install the CLI globally:
 
 ```bash
-npx recall-os --help
+npm install -g recall-os
+recall --help
 ```
 
 (Requires Node.js >= 20. Published at
@@ -97,19 +108,21 @@ git config core.hooksPath .recall/hooks
 
 ## Commands
 
-| Command                        | Purpose                                                     |
-| ------------------------------ | ----------------------------------------------------------- |
-| `recall init`                  | Create neutral repository memory (and a pre-commit hook).   |
-| `recall init --preset <id>`    | Add an opinion pack: rich guidance and proposed ADRs.       |
-| `recall adopt`                 | Inspect an existing repo and propose reviewable memory.     |
-| `recall preset list`           | List built-in presets.                                      |
-| `recall feature create <name>` | Scaffold feature memory (PRD, acceptance, tests, review).   |
-| `recall adr create <title>`    | Create a proposed architecture decision record.             |
-| `recall adr accept <name>`     | Promote a proposed ADR to accepted source-of-truth.         |
-| `recall module create <name>`  | Scaffold module memory (ownership, boundaries, tests).      |
-| `recall skill create <name>`   | Generate a portable AI agent skill (Claude + Agent Skills). |
-| `recall mcp add <server>`      | Generate offline, proposed memory for an MCP server.        |
-| `recall doctor`                | Validate memory health, evidence, and drift.                |
+| Command                            | Purpose                                                                       |
+| ---------------------------------- | ----------------------------------------------------------------------------- |
+| `recall init`                      | Create neutral repository memory (and a pre-commit hook).                     |
+| `recall init --preset <id>`        | Add an opinion pack: rich guidance and proposed ADRs.                         |
+| `recall adopt`                     | Inspect an existing repo and propose reviewable memory.                       |
+| `recall preset list`               | List built-in presets.                                                        |
+| `recall feature create <name>`     | Scaffold feature memory (PRD, acceptance, tests, review).                     |
+| `recall adr create <title>`        | Create a proposed architecture decision record.                               |
+| `recall adr accept <name>`         | Promote a proposed ADR to accepted source-of-truth.                           |
+| `recall adr supersede <old> <new>` | Record a changed decision: mark the old ADR superseded by a new accepted ADR. |
+| `recall module create <name>`      | Scaffold module memory (ownership, boundaries, tests).                        |
+| `recall skill create <name>`       | Generate a portable AI agent skill (Claude + Agent Skills).                   |
+| `recall skill list`                | List the built-in agent skill catalog.                                        |
+| `recall mcp add <server>`          | Generate offline, proposed memory for an MCP server.                          |
+| `recall doctor`                    | Validate memory health, evidence, and drift.                                  |
 
 ## What Doctor Checks
 
@@ -123,6 +136,7 @@ local, and read-only.
 | ADR quality         | An accepted ADR with no meaningful consequences                                         | error / warn |
 | Security            | A security-sensitive feature with no documented security impact                         | error / warn |
 | Drift               | Memory that references a missing, or not-yet-accepted, ADR                              | error / warn |
+| Superseded          | Memory still citing a decision that has been superseded by a newer ADR                  | warning      |
 | Content             | A feature PRD, module, or (once work exists) the threat / security model left as a stub | warning      |
 
 ```txt
@@ -159,17 +173,7 @@ Adding a preset is a small contribution — see [CONTRIBUTING.md](CONTRIBUTING.m
 
 ## How It Works
 
-```txt
-                Recall OS creates and validates memory under docs/ and .recall/
-
-  intent ─┐
-  decisions ─┤        recall init / feature / adr / module        ┌─ humans review
-  ownership ─┼──────────────────────────────────────────────────►│
-  standards ─┤              docs/ + .recall/config.json           └─ agents re-read
-  security ─┘                          │
-                                       ▼
-                                 recall doctor  ──►  0 / 1 / 2  ──►  hook or CI gate
-```
+![How Recall OS works: you capture intent, decisions, ownership, standards, and security with recall init / feature / adr / module; it writes durable, reviewable memory under docs/ and .recall/config.json that humans review in pull requests and agents re-read every session; recall doctor validates it deterministically, returning exit code 0, 1, or 2 for a pre-commit hook or CI gate.](https://raw.githubusercontent.com/Karthick-Ramachandran/recall-os/main/docs/media/how-it-works.png)
 
 ## How agents load the memory
 
@@ -240,6 +244,11 @@ Run the gates above and `recall doctor` before claiming work is complete. See
 [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow and how to add a preset, and
 [SECURITY.md](SECURITY.md) for the security model.
 
+## Acknowledgments
+
+The [landing page](https://recall-os.pages.dev) is deployed with
+[Pagecast](https://github.com/Amal-David/pagecast) — thank you.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).