docs: launch project landing page with demo video

.project-docs/agent-context.md

@@ -0,0 +1,31 @@
+<!-- Synchronized project guidance. Canonical editable path: .project-docs/agent-context.md. -->
+
+# Project guidance
+
+Project knowledge lives under `.project-docs/`.
+
+Before making a non-trivial project-specific claim:
+
+1. read `.project-docs/manifest.yaml`;
+2. follow `.project-docs/navigation.md`;
+3. search the routed locations and read the canonical record plus material
+   related links;
+4. check status, freshness, and sources.
+
+Use `services/` for current systems, `processes/` for exact actions,
+`decisions/` for rationale, `reactions/` for conditional first actions,
+`bugs/` for known failures, and `timeline/` for chronology.
+
+Do not treat observations, stale claims, conflicts, recommendations, or
+unknowns as confirmed facts. Never store, quote, partially reproduce,
+transform, or echo secret values.
+
+Change project guidance only through the `project-documentation` workflow at
+the canonical editable source, `.project-docs/agent-context.md`. Do not edit
+`AGENTS.md` or `CLAUDE.md` directly; both generated targets are byte-identical
+to the canonical source.
+
+After every documentation mutation, run the project-documentation validator.
+If canonical guidance changed, also run the guidance synchronization script
+with `--diff`, `--write`, and `--check`. Documentation work is incomplete until
+validation and synchronization pass.

.project-docs/bugs/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/changelog/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/decisions/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/manifest.yaml

@@ -0,0 +1,31 @@
+schema_version: 1
+entrypoints:
+  project: project.md
+  navigation: navigation.md
+routes:
+  current_state:
+    - project.md
+    - services/
+  how_to:
+    - processes/
+  why:
+    - decisions/
+  incident_first_action:
+    - reactions/
+    - processes/
+    - services/
+  known_problem:
+    - bugs/
+  history:
+    - timeline/
+    - changelog/
+  unresolved:
+    - open-questions.md
+    - observations/
+search_fields:
+  - id
+  - title
+  - summary
+  - tags
+  - canonical_for
+  - related

.project-docs/navigation.md

@@ -0,0 +1,25 @@
+# Documentation navigation
+
+## Search order
+
+1. Classify the question using `manifest.yaml` routes.
+2. Search only routed paths with task terms, identifiers, tags, and synonyms.
+3. Read the best canonical match.
+4. Follow only material `related` links.
+5. Check status, freshness, and sources before using a claim.
+
+The product overview is canonical in `project.md`. Detailed engineering
+rationale remains in the repository's `docs/decisions/` directory and is cited
+as repository evidence rather than duplicated here.
+
+## Stopping rules
+
+- No canonical match means unknown.
+- Observations remain unconfirmed.
+- Stale records require re-verification.
+- Conflicts preserve every sourced version.
+- Recommendations are not current behavior.
+- Missing sources invalidate confirmed claims.
+
+Record missing knowledge in `open-questions.md`; do not invent a project
+default.

.project-docs/observations/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/open-questions.md

@@ -0,0 +1,17 @@
+# Open questions
+
+## Public project surface
+
+- Question: What public domain should be canonical for the project landing page?
+- Status: unknown
+- Needed evidence: a deployed public URL selected by the project owner.
+- Owner: Max Butorin
+- Related: `project.md`
+
+## Release publication
+
+- Question: Which merged version should be the next tagged GitHub and PyPI release?
+- Status: unknown
+- Needed evidence: an explicit release decision from the project owner.
+- Owner: Max Butorin
+- Related: `project.md`

.project-docs/processes/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/project.md

@@ -0,0 +1,52 @@
+---
+id: session-recall-project
+type: project
+title: Session Recall project overview
+summary: Local-first semantic memory shared by Claude Code, Codex, and Cursor through one MCP interface.
+status: confirmed
+tags: [session-recall, semantic-search, mcp, claude-code, codex, cursor]
+canonical_for: [project-overview, product-scope, architecture-entrypoints]
+verified_at: 2026-08-03
+sources:
+  - type: repository
+    reference: README.md
+    confirmed_at: 2026-08-03
+  - type: commit
+    reference: d19054c4a83085ad7e02fb7221b068bc34299534
+    confirmed_at: 2026-08-03
+related: []
+---
+
+# Session Recall project overview
+
+Session Recall gives Claude Code, Codex, and Cursor one searchable memory over
+their local conversation histories. It indexes user and assistant conversation
+surface text for semantic retrieval while preserving tool calls, outputs, and
+reasoning for explicit raw navigation.
+
+## Product boundaries
+
+- The shipped runtime is a Python CLI and MCP server with native host plugin
+  manifests for Claude Code, Codex, and Cursor.
+- Recall is on demand. The project does not proactively inject history into
+  every prompt.
+- Original Claude Code and Codex transcripts stay in place. Cursor sessions are
+  read from the editor's local SQLite store and normalized into durable local
+  snapshots.
+- A bundled local embedding model is the zero-key default. Hosted and
+  user-operated embedding providers are optional.
+- Team sharing is opt-in, end-to-end encrypted, project-scoped, secret-scanned,
+  and approval-gated before an answer leaves its owner's machine.
+
+## Architecture entrypoints
+
+- `src/session_recall/index.py` and `src/session_recall/cursor.py`: source
+  ingestion and incremental reconciliation.
+- `src/session_recall/retrieve.py` and `src/session_recall/store.py`: hybrid
+  semantic and lexical retrieval over SQLite.
+- `src/session_recall/server.py`: the five MCP recall tools.
+- `src/session_recall/cli.py`: setup, indexing, search, diagnostics, and local
+  operations.
+- `src/session_recall/share/`: optional cross-machine question and approval
+  flow.
+- `docs/decisions/`: detailed engineering rationale and invariants.

.project-docs/reactions/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/services/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/timeline/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/validation-allowlist.json

@@ -0,0 +1,143 @@
+{
+  "version": 1,
+  "allow": [
+    {
+      "path": ".github/workflows/publish.yml",
+      "rule": "sensitive-assignment",
+      "literal": "token: write",
+      "reason": "Example GitHub workflow permission syntax, not a credential value."
+    },
+    {
+      "path": ".github/workflows/test.yml",
+      "rule": "personal-path",
+      "literal": "~/.local/share/session-recall/models",
+      "reason": "Example portable application data path used by the test cache."
+    },
+    {
+      "path": "README.es-ES.md",
+      "rule": "personal-path",
+      "literal": "~/.codex/sessions",
+      "reason": "Example portable Codex data path, not a user-specific value."
+    },
+    {
+      "path": "README.es-ES.md",
+      "rule": "personal-path",
+      "literal": "~/.codex/archived_sessions",
+      "reason": "Example portable Codex archive path, not a user-specific value."
+    },
+    {
+      "path": "README.es-ES.md",
+      "rule": "personal-path",
+      "literal": "~/.local/bin",
+      "reason": "Example portable executable path used by pipx."
+    },
+    {
+      "path": "README.es-ES.md",
+      "rule": "personal-path",
+      "literal": "~/.local/share/session-recall/index.db)",
+      "reason": "Example portable index path in diagnostic output."
+    },
+    {
+      "path": "README.es-ES.md",
+      "rule": "personal-path",
+      "literal": "~/.local/share/session-recall/index.db",
+      "reason": "Example portable index path in setup documentation."
+    },
+    {
+      "path": "README.es-ES.md",
+      "rule": "personal-path",
+      "literal": "~/.claude/settings.json",
+      "reason": "Example portable Claude Code settings path."
+    },
+    {
+      "path": "README.es-ES.md",
+      "rule": "personal-path",
+      "literal": "~/meta-docs",
+      "reason": "Example user-selected repository path for meta docs."
+    },
+    {
+      "path": "README.es-ES.md",
+      "rule": "personal-path",
+      "literal": "~/.local/share/session-recall/",
+      "reason": "Example portable Session Recall data directory."
+    },
+    {
+      "path": "README.md",
+      "rule": "personal-path",
+      "literal": "~/meta-docs",
+      "reason": "Example user-selected repository path for meta docs."
+    },
+    {
+      "path": "docs/decisions/2026-06-27-grep-resilient-to-deleted-transcripts.md",
+      "rule": "personal-path",
+      "literal": "/Users/maxim/.claude/projects/-Users-maxim/98688231-0c4e-471d-aec2-a4ee74efda4f.jsonl",
+      "reason": "Historical example path retained as evidence in a public engineering decision."
+    },
+    {
+      "path": "docs/decisions/2026-06-27-grep-resilient-to-deleted-transcripts.md",
+      "rule": "personal-path",
+      "literal": "/Users/maxim",
+      "reason": "Historical example path fragment retained in a public engineering decision."
+    },
+    {
+      "path": "docs/decisions/2026-06-27-grep-resilient-to-deleted-transcripts.md",
+      "rule": "personal-path",
+      "literal": "~/.claude/projects/-Users-maxim/",
+      "reason": "Historical example of Claude Code project-path encoding."
+    },
+    {
+      "path": "docs/decisions/2026-06-27-recall-ergonomics-when-and-recent-sessions.md",
+      "rule": "personal-path",
+      "literal": "~/sidekey)",
+      "reason": "Historical example project path retained as engineering evidence."
+    },
+    {
+      "path": "docs/decisions/2026-07-26-voyage-403-egress-via-netcup.md",
+      "rule": "personal-path",
+      "literal": "~/.local/bin/session-recall{,-mcp}",
+      "reason": "Example portable wrapper executable paths."
+    },
+    {
+      "path": "docs/decisions/2026-07-26-voyage-403-egress-via-netcup.md",
+      "rule": "personal-path",
+      "literal": "~/.claude/settings.json",
+      "reason": "Example portable Claude Code settings path."
+    },
+    {
+      "path": "docs/decisions/2026-07-26-voyage-403-egress-via-netcup.md",
+      "rule": "personal-path",
+      "literal": "~/.zshenv",
+      "reason": "Example portable shell environment path."
+    },
+    {
+      "path": "docs/decisions/2026-07-30-p2p-sharing-v1-security-gate.md",
+      "rule": "personal-path",
+      "literal": "~/.ssh",
+      "reason": "Example portable SSH storage path used in a rejected alternative."
+    },
+    {
+      "path": "docs/decisions/2026-07-31-metadocs-living-project-memory.md",
+      "rule": "personal-path",
+      "literal": "~/.local/share/session-recall/salvage/",
+      "reason": "Example portable local recovery path."
+    },
+    {
+      "path": "skills/setup/SKILL.md",
+      "rule": "sensitive-assignment",
+      "literal": "VOYAGE_API_KEY=…`",
+      "reason": "Example redacted environment-variable placeholder, not a credential value."
+    },
+    {
+      "path": "skills/setup/SKILL.md",
+      "rule": "personal-path",
+      "literal": "~/.local/share/session-recall/",
+      "reason": "Example portable Session Recall data directory."
+    },
+    {
+      "path": "skills/setup/SKILL.md",
+      "rule": "personal-path",
+      "literal": "~/Sync/sr-share",
+      "reason": "Example user-selected shared-folder transport path."
+    }
+  ]
+}

AGENTS.md

@@ -0,0 +1,31 @@
+<!-- Synchronized project guidance. Canonical editable path: .project-docs/agent-context.md. -->
+
+# Project guidance
+
+Project knowledge lives under `.project-docs/`.
+
+Before making a non-trivial project-specific claim:
+
+1. read `.project-docs/manifest.yaml`;
+2. follow `.project-docs/navigation.md`;
+3. search the routed locations and read the canonical record plus material
+   related links;
+4. check status, freshness, and sources.
+
+Use `services/` for current systems, `processes/` for exact actions,
+`decisions/` for rationale, `reactions/` for conditional first actions,
+`bugs/` for known failures, and `timeline/` for chronology.
+
+Do not treat observations, stale claims, conflicts, recommendations, or
+unknowns as confirmed facts. Never store, quote, partially reproduce,
+transform, or echo secret values.
+
+Change project guidance only through the `project-documentation` workflow at
+the canonical editable source, `.project-docs/agent-context.md`. Do not edit
+`AGENTS.md` or `CLAUDE.md` directly; both generated targets are byte-identical
+to the canonical source.
+
+After every documentation mutation, run the project-documentation validator.
+If canonical guidance changed, also run the guidance synchronization script
+with `--diff`, `--write`, and `--check`. Documentation work is incomplete until
+validation and synchronization pass.

CLAUDE.md

@@ -0,0 +1,31 @@
+<!-- Synchronized project guidance. Canonical editable path: .project-docs/agent-context.md. -->
+
+# Project guidance
+
+Project knowledge lives under `.project-docs/`.
+
+Before making a non-trivial project-specific claim:
+
+1. read `.project-docs/manifest.yaml`;
+2. follow `.project-docs/navigation.md`;
+3. search the routed locations and read the canonical record plus material
+   related links;
+4. check status, freshness, and sources.
+
+Use `services/` for current systems, `processes/` for exact actions,
+`decisions/` for rationale, `reactions/` for conditional first actions,
+`bugs/` for known failures, and `timeline/` for chronology.
+
+Do not treat observations, stale claims, conflicts, recommendations, or
+unknowns as confirmed facts. Never store, quote, partially reproduce,
+transform, or echo secret values.
+
+Change project guidance only through the `project-documentation` workflow at
+the canonical editable source, `.project-docs/agent-context.md`. Do not edit
+`AGENTS.md` or `CLAUDE.md` directly; both generated targets are byte-identical
+to the canonical source.
+
+After every documentation mutation, run the project-documentation validator.
+If canonical guidance changed, also run the guidance synchronization script
+with `--diff`, `--write`, and `--check`. Documentation work is incomplete until
+validation and synchronization pass.