@pcircle/footprint 1.6.0 → 1.7.0

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -3,7 +3,15 @@
 [![npm version](https://img.shields.io/npm/v/@pcircle/footprint)](https://www.npmjs.com/package/@pcircle/footprint)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Project site: [footprint.memesh.ai](https://footprint.memesh.ai/)
+Read in:
+[English](../../README.md)
+|
+[繁體中文](../../README.zh-TW.md)
+|
+[日本語](../../README.ja.md)
+
+Project site:
+[footprint.memesh.ai](https://footprint.memesh.ai/)
 
 `@pcircle/footprint` is a local-first MCP server for AI-assisted work continuity. It gives you one place to:
 
@@ -55,6 +63,17 @@ If you want Footprint to suggest the right context before a run begins:
 footprint run codex --prepare-context -- <args...>
 ```
 
+### Choose Your Next Read
+
+- Install and first-run setup:
+  [Getting Started](../../docs/getting-started.md)
+- Environment and deployment details:
+  [Configuration](../../docs/configuration.md)
+- MCP tool walkthrough:
+  [MCP Tools Overview](../../docs/mcp-tools.md)
+- Full docs map:
+  [Docs Index](../../docs/README.md)
+
 ### Install And Configure
 
 ```bash
@@ -101,6 +120,12 @@ footprint demo --host 127.0.0.1 --port 4310
 footprint demo --open
 ```
 
+Repo-local shortcut:
+
+```bash
+pnpm --dir packages/mcp-server demo:live
+```
+
 Recorder inspection commands:
 
 ```bash
@@ -135,33 +160,39 @@ footprint context activate <context-id> [--cwd <path>]
 footprint demo [--host <address>] [--port <number>] [--open]
 ```
 
+Compatibility aliases:
+
+```bash
+footprint list-sessions [--query "<text>"] [--issue-key "<issue-key>"] [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>]
+footprint get-session <session-id> [--message-limit <n>] [--message-offset <n>] [--trend-limit <n>] [--trend-offset <n>] [--timeline-limit <n>] [--timeline-offset <n>] [--artifact-limit <n>] [--artifact-offset <n>] [--narrative-limit <n>] [--narrative-offset <n>] [--decision-limit <n>] [--decision-offset <n>]
+footprint export-sessions [<session-id> ...] [--query "<text>"] [--issue-key "<issue-key>"] [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>] [--group-by <issue|family>]
+footprint get-session-messages <session-id> [--limit <n>] [--offset <n>]
+footprint get-session-trends <session-id> [--limit <n>] [--offset <n>]
+footprint get-session-timeline <session-id> [--limit <n>] [--offset <n>]
+footprint get-session-artifacts <session-id> [--limit <n>] [--offset <n>]
+footprint get-session-narrative <session-id> [--kind <journal|project-summary|handoff>] [--limit <n>] [--offset <n>]
+footprint get-session-decisions <session-id> [--limit <n>] [--offset <n>]
+footprint search-history "<query>" [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>]
+footprint get-history-trends [--query "<text>"] [--issue-key "<issue-key>"] [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>] [--group-by <issue|family>]
+footprint get-history-handoff [--query "<text>"] [--issue-key "<issue-key>"] [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>] [--group-by <issue|family>]
+footprint list-contexts
+footprint get-context <context-id>
+footprint resolve-context [--session <session-id>] [--cwd <path>] [--title "<text>"] [--host <claude|gemini|codex>]
+footprint prepare-context [--session <session-id>] [--cwd <path>] [--title "<text>"] [--host <claude|gemini|codex>] [--interactive] [--json]
+footprint confirm-context-link <session-id> [<session-id> ...] [--context <context-id>] [--label "<label>"] [--set-preferred]
+footprint reject-context-link <session-id> --context <context-id>
+footprint move-session-context <session-id> [--context <context-id>] [--label "<label>"] [--set-preferred]
+footprint merge-contexts <source-context-id> <target-context-id>
+footprint split-context <context-id> --sessions <session-id,session-id,...> [--label "<label>"] [--set-preferred]
+footprint set-active-context <context-id> [--cwd <path>]
+```
+
 Add `--json` to the query commands above when you want scriptable output.
 
 ### Run As An MCP Server
 
 When invoked without a CLI subcommand, Footprint starts the MCP server on stdio.
 
-### Manual MCP Configuration
-
-Claude Desktop example:
-
-```json
-{
-  "mcpServers": {
-    "footprint": {
-      "command": "npx",
-      "args": ["@pcircle/footprint"],
-      "env": {
-        "FOOTPRINT_DATA_DIR": "/path/to/footprint-data",
-        "FOOTPRINT_PASSPHRASE": "your-secure-passphrase"
-      }
-    }
-  }
-}
-```
-
-For Claude Code, use the same server definition in `~/.claude/mcp_settings.json`.
-
 ## Product Surfaces
 
 ### Session History And Context Memory
@@ -209,6 +240,8 @@ Primary UI resources:
 - `ui://footprint/session-dashboard.html`
 - `ui://footprint/session-detail.html`
 
+The session dashboard now combines recent sessions, confirmed canonical contexts, a handoff-oriented scope summary, pinned `search-history` matches, and recurring execution-backed issue trends. It supports interactive query, issue key, host, status, and trend-grouping filters; search, handoff, trend, and context cards can drill directly into session detail or tighten the current dashboard investigation scope. The dashboard now also paginates recent sessions, search matches, and recurring trends with server-backed `limit` / `offset` calls instead of truncating large histories in the client. Those query and search surfaces are now backed by cached SQLite history indexes, so large histories do not require a full JavaScript detail scan just to filter, count, or aggregate matching sessions. The dashboard can also export the current filtered session set directly as a ZIP bundle. The session detail surface now renders recurring trend context for the current session, including the latest related sessions for each recurring issue so investigators can jump across retries without going back to the dashboard, and `footprint session show --json` / `get-session` include the same server-backed trend summary. Trend and handoff surfaces now carry blocker state plus remediation tracking, so repeated failures can be distinguished from recovered or regressed clusters instead of only reporting the latest outcome string. `get-session` now returns paginated transcript, recurring-trend, and timeline slices with page metadata, while `get-session-messages`, `get-session-trends`, `get-session-timeline`, `get-session-artifacts`, `get-session-narrative`, `get-session-decisions`, and the matching CLI commands support `--limit` / `--offset` for large-session inspection. `footprint session show` / `footprint get-session` also expose trend, artifact, narrative, and decision preview pagination through `--trend-*`, `--artifact-*`, `--narrative-*`, and `--decision-*` flags so the condensed CLI view does not need to materialize full derived histories just to render a handoff preview. Deterministic artifact metadata now also carries dependency actions, dependency names, failure signatures, lint rule IDs, test suite/case identifiers, and manifest or lockfile scope so CLI, MCP, UI, and export flows can expose richer execution context without reparsing raw transcript text. Semantic project summaries and handoff narratives now consume that metadata directly, so recurring clusters and dependency changes are described with concrete lint rules, failing test cases, dependency install targets, and manifest/lockfile updates instead of only generic command labels. The human-readable `footprint session show` output is now a condensed handoff/debug report with recurring trend, artifact, decision, and transcript/timeline previews instead of a raw full-session dump. From that detail surface, investigators can now load cross-session issue or family handoff summaries, review the currently linked canonical context, confirm or reject suggested context candidates, move a session into another context, set the preferred workspace context, load more trend/artifact/transcript/timeline/narrative/decision slices on demand, and export either the current session or the selected scope directly as a ZIP archive. The new context-memory layer uses that same session history to suggest likely canonical contexts, but it never auto-links canonical membership without an explicit confirm action. `resolve-context` returns candidates, confidence, reasons, and `confirmationRequired` so an agent host or interactive CLI can ask the user when evidence is ambiguous. `footprint context prepare --interactive` and `footprint run ... --prepare-context` are the shell-side bridge for that contract: they prompt before the session continues, confirm the chosen context, and then record `context.resolved` / `context.updated` timeline events without requiring the MCP server itself to block on user input. Once confirmed, `get-context` returns the latest valid direction for that context plus blockers, open questions, active decisions, superseded decisions, and the recent session trail. `get-history-handoff` / `footprint history handoff` summarize blockers, recoveries, follow-ups, and recent sessions for the current scope while following the same `issue` vs `family` grouping mode as `get-history-trends`; both surfaces now aggregate from materialized trend-attempt rows instead of rebuilding each session’s derived tree on demand. `get-history-trends` and `footprint history trends` now support `groupBy=family` / `--group-by family` when exact issue keys are too fine-grained. Export bundles now include machine-readable JSON snapshots, top-level recurring trend and history-handoff summaries, human-readable `history-handoff.md`, per-session `handoff.md` / `transcript.md` files, the selected `historyGrouping`, and manifest selection metadata when the export was created from filters.
+
 ### Encrypted Evidence
 
 Use the evidence flow when you need a discrete preserved record of a conversation.
@@ -231,6 +264,27 @@ Primary UI resources:
 - `ui://footprint/detail.html`
 - `ui://footprint/export.html`
 
+## Manual MCP Configuration
+
+Claude Desktop example:
+
+```json
+{
+  "mcpServers": {
+    "footprint": {
+      "command": "npx",
+      "args": ["@pcircle/footprint"],
+      "env": {
+        "FOOTPRINT_DATA_DIR": "/path/to/footprint-data",
+        "FOOTPRINT_PASSPHRASE": "your-secure-passphrase"
+      }
+    }
+  }
+}
+```
+
+For Claude Code, use the same server definition in `~/.claude/mcp_settings.json`.
+
 ## Storage Model
 
 Footprint uses one local SQLite database with three logical models:
@@ -241,15 +295,6 @@ Footprint uses one local SQLite database with three logical models:
 
 Evidence content is encrypted at rest. Session history is preserved as raw transcript plus raw timeline, derived views can be regenerated through `reingest-session`, and session exports package both raw and derived views into a portable ZIP archive. Context threading is suggestion-first and correction-driven: unresolved sessions stay isolated until the user confirms a canonical link. Cross-session filtering is backed by cached session-history text and exact issue-key rows inside SQLite so search and list surfaces stay incremental as histories grow.
 
-## Security
-
-- **Encryption**: XChaCha20-Poly1305 (256-bit)
-- **Key Derivation**: Argon2id (OWASP recommended)
-- **Storage**: Local SQLite with encrypted BLOBs
-- **No cloud, no tracking, no data collection**
-
-> **Store your password securely** — loss means permanent data loss.
-
 ## Architecture
 
 Key runtime components:
@@ -261,11 +306,14 @@ Key runtime components:
 - SQLite schema and persistence in `src/lib/storage/`
 - MCP app resource registration in `src/ui/register.ts`
 
-See [ARCHITECTURE.md](./ARCHITECTURE.md) for further reading.
+Further reading:
+
+- [Architecture](./ARCHITECTURE.md)
+- [Docs Index](../../docs/README.md)
 
 ## Prompts
 
-Footprint registers three prompts for MCP clients:
+Footprint also registers three prompts for MCP clients:
 
 - `footprint-skill`
 - `footprint-quick-ref`
@@ -273,17 +321,39 @@ Footprint registers three prompts for MCP clients:
 
 ## Development
 
+Build and test:
+
+```bash
+pnpm --dir packages/mcp-server build
+pnpm --dir packages/mcp-server demo:live
+pnpm --dir packages/mcp-server test:pack-smoke
+pnpm --dir packages/mcp-server test:publish-gate
+pnpm --dir packages/mcp-server test:real-host-smoke
+# macOS only, requires python3 on PATH
+pnpm --dir packages/mcp-server test:macos-smoke
+pnpm --dir packages/mcp-server test:run
+pnpm --dir packages/mcp-server test:linux-smoke
+pnpm --dir packages/mcp-server test:browser
+```
+
+UI-only build:
+
 ```bash
-git clone https://github.com/PCIRCLE-AI/footprint-mcp.git
-cd footprint-mcp
-pnpm install
-pnpm build
-pnpm test:run
+pnpm --dir packages/mcp-server build:ui
 ```
 
-Repository CI runs Ubuntu and macOS jobs: Ubuntu covers install, lint, tarball install smoke, the default Vitest suite, the Linux PTY smoke path, browser-mode session UI tests, and the package publish gate; macOS covers recorder-focused PTY tests plus a real BSD `script -r` smoke path.
+Repository CI now runs Ubuntu and macOS jobs: Ubuntu covers install, lint, tarball install smoke, the default Vitest suite, the Linux PTY smoke path, browser-mode session UI tests, and the package publish gate; macOS covers recorder-focused PTY tests plus a real BSD `script -r` smoke path.
+
+`pnpm --dir packages/mcp-server test:publish-gate` is the package-level release check. It runs audit, build, the package Vitest suite, and the tarball install smoke so `prepublishOnly` blocks releases that are not installable from the packed artifact.
+
+Releases now have two supported paths:
 
-`pnpm test:publish-gate` is the package-level release check. It runs audit, build, the package Vitest suite, and the tarball install smoke so `prepublishOnly` blocks releases that are not installable from the packed artifact.
+- local maintainer publish with `npm login` then `pnpm release:npm`
+- GitHub Actions publish through `.github/workflows/npm-publish.yml`
+
+Schema upgrades are exercised through legacy `v3` / `v4` / `v6` database fixtures, and older databases now backfill materialized history caches and trend-attempt rows during upgrade instead of waiting for the first query to discover missing rows.
+
+`pnpm --dir packages/mcp-server test:real-host-smoke` is an optional manual validation pass. It discovers installed `claude`, `gemini`, and `codex` binaries, skips hosts that are missing, and for hosts that are present it records a real `--version` session and verifies the stored transcript and recorder metadata.
 
 Set `FOOTPRINT_DEBUG_PERF=1` when you want lightweight timing traces for reingest, history query, and export paths while debugging large session sets.
 
@@ -292,8 +362,5 @@ Set `FOOTPRINT_DEBUG_PERF=1` when you want lightweight timing traces for reinges
 - Repository: <https://github.com/PCIRCLE-AI/footprint-mcp>
 - Package: <https://www.npmjs.com/package/@pcircle/footprint>
 - Project site: <https://footprint.memesh.ai/>
+- Homepage: <https://footprint.memesh.ai>
 - Issues: <https://github.com/PCIRCLE-AI/footprint-mcp/issues>
-
-## License
-
-MIT License — see [LICENSE](./LICENSE) for details.