@unpolarize/knowledge-planning 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unpolarize
+
+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,92 +1,139 @@
 # @unpolarize/knowledge-planning
 
-A durable, git-backed, **life-wide** planning system — software, career, finances, family,
-research — over a markdown SSOT. Combines Nimbalyst (plans/tracker/session-kanban) and Vibe
-Kanban (card → agent execution) patterns, wired to the `~/docs` knowledge base (`blocked_by`
-edges) and the portable `~/.sessions` corpus (`planning_refs`).
+**KP** — a durable, git-backed planning CLI and library over a **markdown SSOT**. It makes
+the work that ideas and agent sessions advance first-class: every task, idea, plan, and thought
+is a markdown file with typed frontmatter, addressable by a stable id, queryable, and linkable to
+coding sessions.
 
-Implements the design in `~/docs/knowledge/tech/agents/knowledge-planning-design.md`.
+- **Life-wide, not just software** — model any set of domains (work, life, whatever you define).
+- **Plain files, in git** — the store is a directory of markdown; nothing is locked in a database.
+- **CLI + library + optional web UI** — script it, embed it, or serve a localhost dashboard.
 
-## Why
+## Install
 
-Planning was scattered across a Google Doc, `notes.md`, and `tasks.md`, with no durable,
-queryable, session-linked home for ideas/plans/daily work. This makes the *work that agent
-sessions advance* first-class, in git, addressable by stable id.
+```bash
+npm i -g @unpolarize/knowledge-planning     # global CLI: `kp` / `knowledge-planning`
+# or, no install:
+npx @unpolarize/knowledge-planning --help
+# or as a library:
+npm i @unpolarize/knowledge-planning
+```
+
+Requires **Node ≥ 22** (uses the built-in `node:sqlite` for the read index — no native modules).
 
-## Data / code split
+## The store (your data)
 
-This repo is **tool source only**. The planning **data** (the SSOT) lives in the knowledge base
-at **`~/docs/planning`**, and execution **sessions** live in **`~/.sessions`** (separate git repos).
-The CLI defaults its store root to `~/docs/planning` (override with `--root` / `$KP_ROOT`).
+The **data** lives wherever you point KP — it is separate from this package. Set the store root
+with `--root <dir>` or `$KP_ROOT` (default: `~/.knowledge-planning`). A store is just:
 
 ```
-~/projects/unpolarize/knowledge-planning   ← THIS repo (code)
-  src/
-    schema/            # Zod entities + frontmatter parse/serialize
-    store/             # markdown read/write, edges
-    index/             # node:sqlite projection (objects, edges, fts, blocked-by, daily board)
-    graph/             # GraphData for the CSV webview
-    kb-bridge/         # resolve KnowledgeRef → ~/docs; decision detection
-    migrate/           # Google Doc / notes.md bullets → seed objects
-    cli/               # the `kp` command
-  scripts/seed.ts      # reproducible dogfood seed (writes to ~/docs/planning)
-
-~/docs/planning                            ← the DATA store (SSOT, in the KB)
-  config.json          # domains, kb_root (~/docs), sessions_root (~/.sessions)
-  domains/ catalog/ projects/ ideas/ plans/ tasks/ daily/ reflections/ insights/
-  edges.jsonl          # explicit edges (append-only; rebuildable from frontmatter)
-  .index/planning.db   # node:sqlite projection (gitignored, rebuilt by `kp reindex`)
+<store>/
+  config.json        # domains, kb_root, sessions_root, optional project rules
+  ideas/ plans/ tasks/ thoughts/ projects/ domains/ daily/ reflections/ insights/
+  edges.jsonl        # explicit typed edges (append-only; rebuildable from frontmatter)
+  .index/planning.db # node:sqlite projection (gitignored; rebuilt by `kp reindex`)
+```
+
+`config.json` (all optional; sensible defaults):
+
+```jsonc
+{
+  "domains": ["work", "life"],
+  "kb_root": "/path/to/knowledge-base",     // where blocked_by / cites refs resolve
+  "sessions_root": "/path/to/session-store", // git session corpus for planning_refs
+  "project_rules": [                         // optional: derive-projects id/text rules
+    { "project": "projects/my-app", "patterns": ["my-app", "\\bMYAPP\\b"] }
+  ],
+  "project_id_rules": [{ "pattern": "^tasks/myapp-", "project": "projects/my-app" }]
+}
 ```
 
+Keep your store in its own git repo to get durable, cross-machine history for free.
+
 ## Entities
 
-`Domain` · `Project` (wraps projects-catalog + KB folder) · `CatalogEntry` (non-repo pursuit) ·
-`Idea` (capture→refine→accepted→…) · `Plan` (speckit dev / goal+steps life) · `Task` (kanban
-lanes) · `DailyPlan` · `Reflection` (human) · `Insight` (AI). Edges via frontmatter
+`Domain` · `Project` · `CatalogEntry` · `Idea` (capture→refine→accepted→…) · `Plan`
+(dev goal+steps / life goal) · `Task` (kanban lanes) · `Thought` (captured prose, convertible to
+ideas/tasks) · `DailyPlan` · `Reflection` · `Insight`. Typed edges live in frontmatter
 (`blocked_by`, `depends_on`, `cites`, `related`, `promoted_to`, `linked_sessions`) unioned with
-`edges.jsonl`.
+`edges.jsonl`. All schemas are Zod-validated and `.passthrough()`, so unknown keys survive a
+round-trip.
 
-**Knowledge blocks work:** a `blocked_by` edge points at a `~/docs` article and is only
-*resolvable* once that article records a decision (`decision:` frontmatter or a `## Decision`
-section) — so the blocker tracks a real artifact instead of rotting.
+**Knowledge can block work:** a `blocked_by` edge points at a knowledge-base article and is only
+*resolvable* once that article records a decision — so a blocker tracks a real artifact instead of
+rotting.
 
 ## CLI
 
-No build step — Node ≥22 runs the TypeScript directly; `node:sqlite` needs no native module.
-
 ```bash
-node src/cli/index.ts <command>     # or: npm run kp -- <command>
+kp <command> [--root <store>]
 
-reindex                         # rebuild .index/planning.db
-list [--type T] [--status S]    # list objects
+reindex                          rebuild the .index/planning.db projection
+list [--type T] [--status S] [--project P]
 daily [--date today] [--carry-over]
-blocked                         # objects blocked_by unresolved knowledge
-graph [--json]                  # nodes/edges
-capture "<text>" [--domain D]   # quick-capture an idea
-promote <ideaId> [--to planId]  # idea → plan (+lineage)
-link-session <objectId> <uuid>  # bidirectional: linked_sessions ↔ session planning_refs
-insight <file> --source S       # ingest digest bullets → Insight
-set-status <id> <status>        # board lane / accept
-export [--date today]           # one-shot JSON snapshot (consumed by the CSV planning mode)
-doctor                          # config, counts, fts, blocked, warnings
+board                            alias for daily
+blocked                          objects blocked_by unresolved knowledge
+graph [--json]                   nodes/edges
+capture "<text>" [--domain D]    quick-capture an idea
+create "<title>" [--type task|idea|plan|thought] [--status S --domain D --priority p0-p3 --due DATE]
+promote <ideaId> [--to planId]   idea → plan (+ lineage)
+set-status <id> <status> [--note "…"]   change status; --note appends a Resolution section
+set-due <id> <date|->            set/clear due date
+set-priority <id> <p0-p3|->      set/clear priority
+set-project <id> <project|->     assign/clear project
+recategorize <id> [--to-type T --domain D --lane L]
+link-session <id> <uuid>         bidirectional: linked_sessions ↔ session planning_refs
+ingest-gdoc <file> [--domain D --max N]        NEW bullets → tasks/ideas (provenance-stamped)
+ingest-thoughts <file> [--all --max N]         NEW prose paragraphs → thoughts
+derive-projects [--dry-run --force]            label objects by config project rules
+calendar [--from D] [--to D]
+lookback [<date>|today]          what happened that day (sessions + touched items)
+serve [--port 4622]              localhost web dashboard (board / calendar / topics / day)
+export [--date today]            one-shot JSON snapshot (for host integrations)
+show <id>                        rich JSON detail (body + resolved refs + children)
+doctor                           config, counts, index, blocked, warnings
+```
+
+No build step is needed to run from a checkout (`node src/cli/index.ts <cmd>`); the published
+package ships compiled JS.
+
+## Library
+
+```ts
+import { Store, PlanningIndex, buildGraph, commands } from '@unpolarize/knowledge-planning';
+
+const store = new Store(process.env.KP_ROOT!);        // a store directory
+const idx = new PlanningIndex(store);
+console.log(commands.cmdExport(store, idx, store.config(), commands.today()));
 ```
 
-`KP_ROOT` (or `--root`) overrides the store root (defaults to this package root).
+Exports the store reader/writer, the Zod entity schemas, the SQLite index/projection, the graph
+builder, the markdown-ingest helpers, and the `commands` namespace (every CLI operation).
+
+## Web dashboard
+
+`kp serve` starts a zero-dependency localhost dashboard (board with drag-and-drop, calendar,
+topics, day lookback) over the same store. It binds `127.0.0.1` only — it is unauthenticated and
+meant for local use.
 
-## Integrations
+## Host integrations
 
-- **`~/docs` agent skills:** `/planning-daily`, `/planning-capture`, `/planning-refine`,
-  `/planning-promote`, `/planning-link-session`, `/planning-blocked-by`, `/planning-insight`,
-  `/planning-reflect` (in `~/docs/.claude/commands/`).
-- **Sessions:** `code-sessions` `SessionSchema` carries `planning_refs[]` + `phase`; `kp
-  link-session` writes both sides.
-- **Code Sessions VS Code:** a **Planning** activity-bar container (Today / Inbox / Projects
-  trees, kanban board + graph webviews, status bar) reads this store via `kp export`.
-- **Daily workflow:** the Google Doc stays the mobile capture surface; planning *ingests* from
-  `raw/google-docs/personal-todo-notes.md` + `notes.md` rather than replacing it.
+`kp export` emits a single JSON snapshot that a host UI can render; `kp show <id>` returns rich
+per-object detail. This is how editor extensions and other front-ends consume KP without importing
+its internals — they shell out to the CLI (or import the library) and read JSON.
+
+## How to consume it (summary)
+
+- **CLI**: `npx @unpolarize/knowledge-planning` or a global install → the `kp` binary.
+- **Library**: `import … from '@unpolarize/knowledge-planning'` (typed; ships `.d.ts`).
+- **JSON bridge**: `kp export` / `kp show` for any front-end (the decoupled, version-independent path).
 
 ## Tests
 
 ```bash
-npm test        # vitest — schema, store, kb-bridge, migrate, index, graph, cli (29 tests)
+npm test        # vitest — schema, store, kb-bridge, migrate, index, graph, cli, serve
 ```
+
+## License
+
+MIT