@unpolarize/knowledge-planning

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.

• 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.

Install

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).

The store (your data)

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:

<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):

{
  "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 · 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. All schemas are Zod-validated and .passthrough(), so unknown keys survive a round-trip.

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

kp <command> [--root <store>]

reindex                          rebuild the .index/planning.db projection
list [--type T] [--status S] [--project P]
daily [--date today] [--carry-over]
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

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()));

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.

Host integrations

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

npm test        # vitest — schema, store, kb-bridge, migrate, index, graph, cli, serve

License

MIT