projectkeeper 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+What changed for someone who uses ProjectKeeper, newest first. Versions follow [Semantic Versioning](https://semver.org/).
+
+## 1.0.0 — first release (2026-10-14)
+
+What it includes:
+
+**The workbench** — a local web page at `127.0.0.1`.
+
+- **Project graph**, in three faces: `Graph` (a story map: the owner's words, product and goals on top, areas across, plans down, each piece of work in its cell, earlier plans rolled up), `List` (area by area, what was planned beside what happened) and `Code` (which code belongs to which product area, who built it, whether the current plan uses it).
+- **Each piece of work with its steps** — planned, dispatched, delivered, checked, fixed, merged — and the commits, reports and verdicts behind each.
+- **Breakpoints and send-backs**: where a step should be and has no trace, and what should go back to the work or the plan, with text to copy for an agent.
+- **Notes log**: the Keeper's notes to the owner, those for decision with options.
+- **Change log**, **Agent context**, **Project scope**, and a bilingual **Vocabulary**.
+- **Keeper** pages: the takeover with three depths, the daily schedule, model provider and keys, a model for each step, backup keys, the project-folder authorization, usage by round and model, and every round as a tree of its steps.
+- A conversation with the Keeper (`Ask Keeper`).
+- A folder chooser where a location is typed (`Add project`, a scope item's path): `Browse…` lists folders to walk and pick from, with repositories and worktrees marked; a typed or pasted path works as before.
+- Answers only at its own local address and, in a browser, only to its own pages: another site's page open in the same browser can neither read the workbench nor post to it.
+- Four themes.
+
+**The Keeper** — the resident agent.
+
+- A **takeover** in two rounds: a first usable picture, then a deepening at the depth chosen (`Full`, `Focused`, `First picture only`).
+- **Daily upkeep** on a schedule the owner sets, or on `Follow up`.
+- A **ledger** built by a program, without a model: commits, document versions, numbering, verdicts, code structure, sessions.
+- Each round: session drafts, a main agent that sends sub-agents by question, a synthesis in a session of its own, an independent spot check, and the program's own checks.
+- Reads Claude Code and Codex session logs, git repositories and worktrees, and plain folders.
+- Reads a project without changing it; one folder of its own inside the project only with the owner's authorization, given and withdrawn on the Keeper page (`Project folder`).
+
+**For agents** — the `pk` command: `context`, `get`, `options`, `ask`, `help`.
+
+- `pk mcp`: the same reading commands and the table check as a local MCP server, for clients that take their tools over MCP; configurations for Claude Code, Codex and Cursor in [docs/pk.md](docs/pk.md#as-an-mcp-server).
+
+**The table** — a takeover any agent can do (`template/`): the agent reads the project in its own way and fills one JSON table, `projectkeeper/project.json`. `pk check` checks it: the shape, the ids, and every source against the project, quotes word for word. `pk import` takes it in as the project's picture, drawn by the same Graph, List and Code views. `pk sessions` writes the session material the table quotes the owner from — every owner message of the project's agent sessions, after the agent's answer it replies to — into ProjectKeeper's own folder for the project, never into the project.
+
+A project taken over by the table is followed up by carrying the same table on. This happens when you press Follow up, on the daily schedule, or on Continuous. The Keeper gets a brief of what changed since the table's `asOf`: the commits, the documents they changed, and your new messages in the sessions. It edits a copy of the table and hands it in. The table is taken in only when it passes the same check as `pk check`; a table with any problem goes back to the Keeper with the list. A table kept in ProjectKeeper's own folder keeps a git history of its versions there. Such a project never runs the takeover's rounds.
+
+**Models** — bring your own key, through pi. Run so far on DeepSeek and Zhipu GLM.
+
+**The demo** — `npm run demo`: an invented project, already organized, with no key and no network.
+
+**Systems** — Windows and macOS.
+
+- On macOS: a project's sessions are looked for where Claude Code and Codex keep them on a Mac; a file named in another case, or in the other Unicode form of an accented, Korean or Japanese character, is the same file; the Keeper's shell is `/bin/bash`, and its check knows paths that start at `/` and macOS's own tools (AppleScript, the clipboard, the keychain and a Spotlight search of the whole machine are refused); `Open in pi` opens Terminal; a location can be typed with `~`.
+- On macOS and Linux the saved keys are readable by their owner alone.
+- The workbench says at its start when git is missing or too old.
+
+Known limits:
+
+- Linux is not supported yet. On macOS the test suite passes on GitHub's runners, and ProjectKeeper has not yet had daily use there.
+- On a Mac volume formatted case-sensitive, two names that differ only in case are taken for one.
+- A project whose own path is longer than 246 characters is read without its git history, and one longer than 251 cannot be organized: git and the Keeper cannot work in a directory that deep on Windows. Files deep inside a project are fine.
+- The picture has errors, and differs from run to run on the same project. See [docs/cost-and-quality.md](docs/cost-and-quality.md).
+- The workbench opens only as `127.0.0.1`, `localhost` or `[::1]` with its port, not under a hosts-file alias or behind a proxy: there it answers `403`.
+- Not published to npm; run from a clone.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProjectKeeper contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

package/README.md

@@ -1,3 +1,284 @@
-# Temporary Holding Version
+# ProjectKeeper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**AI writes code faster every week. Do you still know whether what it built is what you wanted?**
+
+ProjectKeeper puts what you asked for, the decisions you changed and the work the AI actually finished on one map, shows you where they part, and lets the next agent pick up where the last one stopped — even on a project left half-done. Your own agent takes the project over by reading it as it is and filling in one table; from then on a resident agent keeps the map current every day.
+
+- **Anchored to what you said.** Your words are kept verbatim, with the session they were said in. Where a document has drifted from them, where something you wanted was dropped along the way, or where work grew that you never asked for, ProjectKeeper tells you.
+- **A half-done project, ready to hand over.** Point it at the folder: documents, git history, code and agent sessions become one picture, and one command gives the next agent the context for the work it picks up.
+
+English · [简体中文](README.zh-CN.md)
+
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue)](LICENSE)
+![Node.js 24 or later](https://img.shields.io/badge/node-%E2%89%A5%2024-brightgreen)
+[![CI](https://github.com/feiyanglyy-stack/ProjectKeeper/actions/workflows/ci.yml/badge.svg)](https://github.com/feiyanglyy-stack/ProjectKeeper/actions/workflows/ci.yml)
+![Local-first: no account, no telemetry](https://img.shields.io/badge/local--first-no%20account%2C%20no%20telemetry-success)
+
+![The story map of a real project: the owner's words and the product at the top, goals and product areas across, two earlier plans rolled up, the current plan's work underneath](docs/images/hero-story-map.png)
+
+*One real project on one screen: what the owner asked for, the goals and product areas, two earlier plans, and the current plan's work. Every object opens to its sources.*
+
+## Why
+
+Let AI build a piece of software for long enough and you end up here: the conversations pile up, the plan keeps changing, and the agents have been swapped several times. Every agent says its task is done, yet nobody can say in full what was asked for at first, what changed later, and what was finally built. The answers exist — in documents, commit messages and session logs nobody will read again.
+
+ProjectKeeper works like a project's archivist. It does not write code for the agents; it lines up every request, every change and the work actually finished. Where they do not match, it tells you; when the agent changes, it hands the whole story to the next one.
+
+It is not too late to bring it in halfway: it goes through the sessions, documents and commits already there, and tells you what each version of the requirements was, what it was changed to, and which version is the one built. All of it happens on your machine.
+
+## What you get
+
+- **The whole project on one map.** What you said you wanted, the goals, the product areas, the plans, and each piece of work in its place.
+- **What really happened to each piece of work.** Its steps — dispatched, delivered, reviewed, fixed, merged — each with the commit, report or verdict it rests on, and marked `Inferred` where the Keeper inferred it.
+- **Where a decision came from.** Your own words, quoted verbatim with the session they were said in, and the documents and commits that carried the decision on.
+- **What became of old plans.** Every item of an earlier plan with what happened to it: carried on, moved, deferred or dropped.
+- **What needs you.** Notes that ask for your decision and give options, and send-backs — a review that failed and nobody picked up — ready to copy to an agent.
+- **The right context for the next agent.** One command gives an agent the pack for a work item: what it serves, how it got here, your project's rules, where the code is.
+
+And it stays current: after the takeover, a round runs on the schedule you set, or when you press `Follow up`.
+
+## After one pass
+
+The first pass reads the documents, the git history, the code structure and your agent sessions, and fills three views.
+
+![Graph view after the first pass](docs/images/first-pass-01-story-map.png)
+
+*Graph: your words and the product on top, goals and areas across, earlier plans rolled up, the current plan's work in its cells.*
+
+![List view after the first pass, one area opened](docs/images/first-pass-02b-list-module-open.png)
+
+*List: one area opened. What was planned is on the left; what actually happened is on the right — in progress, merged in which commit, delivered with no check recorded.*
+
+![Code view after the first pass](docs/images/first-pass-03-code-territories.png)
+
+*Code: which code belongs to which product area, which pieces of work built it, how many tests it has, and whether the current plan still uses it.*
+
+**Measured:** this pass took about 50 minutes and about 11 CNY (about $1.5) on DeepSeek. The project is ProjectKeeper's own working repository: about 1,000 files of documents and code (some 470 Markdown documents and 400 source files, about 217,000 lines), about 750 commits and 22 agent sessions.
+
+## After a deepening
+
+A deepening digs the history by question and checks its own work. On the same project it took another 71 minutes.
+
+![A work item with its steps and the evidence for them](docs/images/deepened-02-work-item-steps-and-evidence.png)
+
+*A piece of work with its steps under it — checked, dispatched, delivered, merged — and beside it the code it changed and the commits and review verdicts it came through.*
+
+![An area's requirements, designs and decisions, with one decision's origin](docs/images/deepened-01-intent-chain-and-where-a-decision-came-from.png)
+
+*Where a decision came from: an area's requirements, designs and decisions in one list, and for the one you click, when it was made and the commits that carried it.*
+
+![An earlier plan, each item struck through with what carried it on](docs/images/deepened-03-earlier-generation-what-its-items-became.png)
+
+*What became of an old plan: every item of an earlier generation, struck through, with the current item that carried it on.*
+
+![A note for the owner's decision, with options](docs/images/deepened-05-note-for-the-owner-with-options.png)
+
+*A note that needs you: the question, the Keeper's view, why it matters, three options with what follows from each, and the facts with their sources.*
+
+![Usage by round and by model](docs/images/deepened-06b-keeper-usage-by-model.png)
+
+*What each round used and which model carried which steps. The dollar figure is an estimate at list prices; the bill for this run was lower (see [What a run costs](#what-a-run-costs)).*
+
+![From the map to one work item, its steps, and the code it changed](docs/images/map-to-work-item-to-steps-to-code.gif)
+
+*From the map to one piece of work, to what happened to it, to the code it changed.*
+
+## See it without a key
+
+```sh
+npm run demo
+```
+
+This builds an invented project — Papertrail, a one-person read-later list — already organized, and serves it at `http://127.0.0.1:4880/`. No key, no model, no network; the Keeper's answers in the demo are canned. Everything it writes goes into one folder in your temporary directory.
+
+## Four looks
+
+The workbench comes in four themes; switch with `Theme` in the top bar. Here is the demo project in each.
+
+<table>
+<tr>
+<td width="50%"><img src="docs/images/theme-a1-walnut-workshop.png" alt="The demo project's Graph in the Walnut Workshop theme"><br><b>Walnut Workshop</b> — the default</td>
+<td width="50%"><img src="docs/images/theme-b1-peacock-and-brass.png" alt="The demo project's Graph in the Peacock &amp; Brass theme"><br><b>Peacock &amp; Brass</b></td>
+</tr>
+<tr>
+<td width="50%"><img src="docs/images/theme-d2-warm-clay.png" alt="The demo project's Graph in the Warm Clay theme"><br><b>Warm Clay</b></td>
+<td width="50%"><img src="docs/images/theme-i1-task-console.png" alt="The demo project's Graph in the Task Console theme"><br><b>Task Console</b></td>
+</tr>
+</table>
+
+`Factory` in the same list is the plain built-in look, without a theme.
+
+## Quick start
+
+You need Node.js 24 or later, and git, on Windows or macOS. On a Mac, git comes with the Xcode command line tools (`xcode-select --install`), and Homebrew's `node` is a newer Node than the 24 this is tested on: [what a Mac needs](docs/getting-started.md#on-a-mac).
+
+```sh
+git clone https://github.com/feiyanglyy-stack/ProjectKeeper.git && cd ProjectKeeper
+npm ci
+npm start
+```
+
+Or from npm, without a clone: `npm install -g projectkeeper`, then `projectkeeper serve`; where this page says `npx pk`, use `projectkeeper`.
+
+Then take your project over, in one of two ways.
+
+**With your own agent (recommended).** Claude Code, Codex or any agent you use reads the project and fills in the table:
+
+```sh
+npx pk takeover --project <your project folder> --prepare
+```
+
+This sets up three folders, each with its instructions, in ProjectKeeper's own folder, never in your project:
+- one for the agent that reads your words in your past sessions;
+- one for the agent that reads a copy of the project;
+- one for the main agent that merges the two.
+
+Run the three steps with your agent, then `pk import`, as printed, takes the table in. With Codex, `--run codex` in place of `--prepare` runs the three steps by themselves and takes the table in when it checks clean. Open `http://127.0.0.1:4870/` to see it. How the agents fill the table: [the template](template/FILLING-IN.md).
+
+**With the Keeper and your key.** Open `http://127.0.0.1:4870/`, then four clicks:
+
+1. **Add project** — a name and the folder of your project, typed or picked with `Browse…`. Nothing runs yet.
+2. **Add a key** — on the Keeper page that opens, under `Model provider`: choose the provider, paste the key, `Save`.
+3. **Choose a depth** — `Full`, `Focused` or `First picture only`.
+4. **Start.**
+
+The first picture comes first; the deepening follows if you chose one. Details: [Getting started](docs/getting-started.md).
+
+Either way, add a key for the daily upkeep: the Keeper uses it to carry the picture on as the project changes.
+
+## Models and keys
+
+You bring your own key. The model library underneath ([pi](https://github.com/earendil-works/pi)) lists some forty providers; the ones actually run so far are **DeepSeek** (`deepseek-v4-pro`, `deepseek-flash`) and **Zhipu GLM** (`glm-5.3`, `glm-5.3-flash`). A key you save stays on your machine, in ProjectKeeper's own folder, and is never shown again. Each step of a round can run on its own model, and backup keys take over when one runs out of quota: [Models and keys](docs/models-and-keys.md).
+
+**Subscriptions:** a Claude Pro or Max subscription cannot run the Keeper, because Anthropic allows that login only in Claude Code and on claude.ai; use an API key from the Claude Console. ChatGPT (Codex), Kimi Coding and GitHub Copilot subscriptions connect through pi's login, and none of them has been tested yet: [Subscriptions](docs/models-and-keys.md#subscriptions).
+
+## What a run costs
+
+**A takeover by your own agent** runs on that agent's subscription. On ProjectKeeper's own working repository, Codex took the three steps in about 27 minutes:
+- the reader of the owner's words and the reader of the project ran side by side, in about 18 minutes;
+- then the main agent took 8 minutes.
+
+The table it filled has 75 things the owner wanted, 33 decisions plus 7 boundaries, 36 pieces of work and 18 places where the owner and the project part ways.
+
+**A daily follow-up** runs on your key, and runs no model on a day with nothing new.
+
+**A takeover by the Keeper** (the first pass and a full deepening) of the same project, measured four times:
+
+| Models | Time | Cost |
+|---|---|---|
+| DeepSeek: flash for everything, pro for the final check | 126 min | 29 CNY billed (about $4) |
+| DeepSeek: pro as main agent and for the deepening's sub-agents, flash for the rest | 122 min | 57 CNY billed (about $8) |
+| Zhipu GLM-5.3 as main agent, GLM-5.3-flash for the rest | 198 min | $19 at list price |
+| Zhipu GLM-5.3 for everything | 200 min | $67 at list price |
+
+These are four runs on one project: a loose comparison, not a benchmark. The program changed between the runs (the GLM runs are the older ones), and the main agent of the all-flash run had read the previous run's list of faults in the project it was organizing.
+
+- **The first pass alone** on DeepSeek: about 50 minutes and about 11 CNY with pro as main agent, or about 10 CNY all on flash.
+- **GLM on a Coding Plan subscription** costs far less than the list price. In the maintainer's own terms: a GLM-5.3 first pass is about half of a junior team seat's 5-hour quota, a deepening about one 5-hour quota, a daily follow-up barely moves the quota, and an all-flash run about a third of one 5-hour quota.
+- **The Usage page is an estimate.** It applies a list-price table to the recorded tokens; on the DeepSeek run with pro it showed $14.48 where the account was charged 57 CNY.
+
+What each run got right and what it missed: [Cost and quality](docs/cost-and-quality.md).
+
+## What it does not do, and privacy
+
+- **It does not change your project's files.** It writes to its own home folder (`~/.projectkeeper`). Inside your project it writes one folder of its own, and only after you authorize it.
+- **It listens on `127.0.0.1` only.** No account, and no telemetry of its own.
+- **What leaves your machine** is what goes to the model provider you chose: prompts that contain text from your project — documents, code, commit messages, and what you said in your agent sessions.
+- **It does not write code, run your tests or manage tickets.** It reads, and tells you what it found, with the source of each statement.
+
+More in [Privacy](docs/privacy.md).
+
+## For your agents: `pk`
+
+Agents read the same picture through a command while the workbench is running. Two real outputs from the demo project, shortened where `…` stands:
+
+```text
+$ pk context --work T-18
+# Context for Incoming agent · Work: T-18 Search index incremental rebuild 增量重建 · Kind: Implement
+…
+## Owner's words
+What the owner said that this work traces up to, word for word:
+- `ow_save_fast` · the owner, 2026-09-09 [1]:
+  “Saving has to be faster than deciding where it goes”
+…
+## Open problems
+- The receipt claims a one-minute background refresh; the code does not have it.
+- Is the one-minute refresh claim measured anywhere?
+…
+```
+
+```text
+$ pk get sb_search_refresh
+# Send-back · sb_search_refresh
+Where: Search index incremental rebuild 增量重建 (thread_search_index)
+What: Batch 2 says the index refreshes every minute; the review could not confirm it from the code, and batch 2 was signed off anyway.
+Send back to: Work · Reopen T-18: make the index refresh in the background, or correct the receipt.
+Status: Suggested · Open
+…
+```
+
+For clients that take their tools over MCP (Claude Desktop, Cursor and others), `pk mcp` serves the same commands as a local MCP server: [As an MCP server](docs/pk.md#as-an-mcp-server).
+
+All of it, and how to run these against the demo: [The `pk` command](docs/pk.md).
+
+## How it works
+
+```mermaid
+flowchart LR
+  subgraph P["Your project, read as it is"]
+    D["Documents and plans"]
+    G["Git history"]
+    C["Code"]
+    S["Agent sessions"]
+  end
+  subgraph T["Takeover, by your own agent"]
+    O["Your words, from the sessions"]
+    R["The project, from a copy"]
+    M["Main agent: merges, notes where they part"]
+    O --> M
+    R --> M
+  end
+  subgraph K["ProjectKeeper, on your machine"]
+    L["Ledger: a program records what exists and when"]
+    C2["pk check, pk import: the table against the project"]
+    U["Daily upkeep: the Keeper carries the table on"]
+  end
+  P --> L
+  P --> T
+  M --> C2
+  C2 --> U
+  K --> W["The workbench in your browser"]
+  K --> A["pk, for your agents"]
+```
+
+A program records what exists and when, without a model: every commit, document version, number and session. Your own agent then reads the project in its own way and fills in one table. The program checks the table against the project — every id, every source, every quote word for word — and draws it. From then on the Keeper carries the same table on as the project changes, through the same check. What a program can count or check, the program does; the models' attention goes to judgement.
+
+The Keeper can also take a project over itself, in rounds, with your key. More: [How the Keeper works](docs/how-the-keeper-works.md).
+
+## How it compares
+
+Tools that draw a graph of code structure, such as Understand-Anything, show how the code hangs together; ProjectKeeper's map is of intent and work — what was wanted, planned and done — with the code attached to the product areas it serves. Session-memory tools such as claude-mem capture what agents do from the day you install them; ProjectKeeper takes over what already exists, history included. Spec and task tools such as OpenSpec or Backlog.md work when you and your agents write in their format; ProjectKeeper asks you to write nothing new. It reads what the project already has and keeps it for a person to browse and for agents to query.
+
+## Status and limits
+
+- **v1.0.** It makes mistakes, and it differs from run to run; every statement links to its source so you can check it. The measured runs, and what each missed, are in [Cost and quality](docs/cost-and-quality.md).
+- **Windows and macOS.** ProjectKeeper was built on Windows and is used there every day. It runs on macOS too: its test suite passes there on GitHub's runners, but it has not yet had daily use on a Mac, so expect rough edges — a report of what it did on yours is welcome. Linux is not supported yet.
+- **Names on a Mac.** Two names that differ only in case, or only in the Unicode form of an accented, Korean or Japanese character, are one name to ProjectKeeper, as they are to a Mac's usual volume. On a volume formatted case-sensitive, two files named that way would be taken for one.
+- **A project at a very long path.** Files deep inside a project are read at any length. The project's own path is limited on Windows, and neither git's long-path setting nor Windows' own lifts the limit: at more than 246 characters git cannot open the repository (the files are read without their history, and `Project scope` says so), and at more than 251 the Keeper cannot work in the directory. Move such a project to a shorter path.
+- **It reads sessions from Claude Code and Codex.** Other agents' sessions are not read yet.
+- **The interface is English; the content is in your project's language.** The screenshots are from a Chinese-language project.
+- **The name.** ProjectKeeper was developed under the working name ContextKeeper, and the screenshots show it organizing its own project, which carries that name.
+
+## Documentation
+
+[Getting started](docs/getting-started.md) · [Concepts](docs/concepts.md) · [Models and keys](docs/models-and-keys.md) · [How the Keeper works](docs/how-the-keeper-works.md) · [Cost and quality](docs/cost-and-quality.md) · [The `pk` command](docs/pk.md) · [Privacy](docs/privacy.md) · [FAQ](docs/faq.md) · [Architecture](docs/architecture.md)
+
+## Contributing
+
+Issues and pull requests are welcome: [CONTRIBUTING.md](CONTRIBUTING.md). Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). The themes under `ui/themes/` are not covered by it: [ui/themes/LICENSE.md](ui/themes/LICENSE.md). Third-party material: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+Built with [Claude Code](https://claude.com/claude-code).