cpk docs

cpk docs manages the project knowledge base. Agents use it to record decisions, share discoveries, and retrieve context without needing a full PRD injected into every session.

cpk docs write

Write a document to the knowledge base.

cpk docs write \
  --type learning \
  --title "Safari localStorage purge on tab close" \
  --body "iOS Safari aggressively clears localStorage when a tab closes or the browser is backgrounded for too long. Use sessionStorage with a service worker keep-alive for persistent auth state on mobile. Relevant: src/auth/storage.ts." \
  --tags "auth,mobile,safari,gotcha"

Document created: doc_047
Type: learning
Tags: auth, mobile, safari, gotcha

Flags:

Flag	Required	Description
--type	yes	operational, decision, reference, or learning
--title	yes	Document title
--body	yes	Document content. Markdown supported.
--section	no	Section heading within the document
--tags	no	Comma-separated tags for search and filtering
--author	no	Author name. Defaults to CPK_AGENT value if set.

When to use each type:

Type	Write when…
operational	Documenting how something currently works — a runbook, a setup procedure, a how-to
decision	Recording why an architectural or technical choice was made
reference	Adding an external specification, API contract, schema definition, or the project PRD
learning	An agent discovers something non-obvious, a gotcha, an undocumented behavior, or a useful pattern

cpk docs search

Search the knowledge base by keyword.

cpk docs search "auth token"

doc_001  [reference]  Project PRD                   tags: product
doc_009  [reference]  Auth API contract             tags: auth, api
doc_031  [reference]  JWT token specification       tags: auth, jwt
doc_047  [learning]   Safari localStorage purge...  tags: auth, mobile, safari, gotcha

Filter by document type:

cpk docs search "auth" --type decision

doc_022  [decision]  Why we use JWT over sessions   tags: auth, jwt, decision

Flags:

Flag	Description
--type	Filter results to a specific doc type
--limit	Maximum number of results (default: 10)

Search is full-text across title, body, and tags. Results are ordered by relevance.

cpk docs list

List all documents, optionally filtered by type.

cpk docs list

ID       TYPE        TITLE                              AUTHOR    TAGS
doc_001  reference   Project PRD                        system    product
doc_002  operational Board Setup Guide                  system    setup
doc_009  reference   Auth API contract                  backend   auth, api
doc_017  decision    Database selection rationale        backend   infra, db
doc_022  decision    Why we use JWT over sessions        backend   auth, jwt
doc_031  reference   JWT token specification             backend   auth, jwt
doc_047  learning    Safari localStorage purge behavior  frontend  auth, mobile

cpk docs list --type learning

ID       TYPE      TITLE                              AUTHOR    TAGS
doc_047  learning  Safari localStorage purge behavior  frontend  auth, mobile, safari, gotcha
doc_051  learning  Zod schema inference type widening  backend   typescript, zod

Flags:

Flag	Description
--type	Filter to a specific doc type

cpk docs read

Read the full content of a document.

cpk docs read doc_022

Title:    Why we use JWT over sessions
Type:     decision
Author:   backend
Tags:     auth, jwt
Created:  2025-03-12

We evaluated session cookies (DB-backed) vs JWTs. For our architecture:

- The API is consumed by both web and mobile clients
- Mobile clients can't easily use HttpOnly cookies
- We control all clients (no third-party consumers)

JWT with short-lived access tokens (15 min) and rotating refresh tokens (7 days)
gives us stateless auth for the API while maintaining the ability to invalidate
sessions via the refresh token blacklist.

Trade-off: every access token is valid until expiry even if revoked. Acceptable
given the 15-minute window.

References: src/auth/tokens.ts, src/auth/middleware.ts

Related

• Knowledge Base concepts — doc types, usage patterns, how init seeds the KB