@justestif/pk 0.2.2 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@justestif/pk",
    "type": "module",
-   "version": "0.2.2",
+   "version": "0.3.0",
    "description": "Project knowledge — structured intake, search, and recall",
    "bin": {
       "pk": "dist/index.js"
@@ -33,7 +33,7 @@
    },
    "devDependencies": {
       "@types/bun": "latest",
-      "ajv": "6",
+      "fallow": "^2.67.0",
       "typescript": "latest",
       "xo": "^2.0.2"
    }

package/skill/SKILL.md

@@ -7,48 +7,48 @@ description: "Load when maintaining project knowledge, capturing decisions or qu
 
 Structured project knowledge — intake, search, recall, and audit.
 
-**Search, synthesis, creation, and validation go through MCP tools. Writing note body content uses your standard file Edit tool — but only on paths returned by `pk_new` or `pk_search`, never by navigating the filesystem yourself.**
+Use the `pk` CLI for all knowledge operations. Every command supports `--json` for machine-readable output. Never read or write knowledge files directly — always go through `pk`.
 
-## Tools
+## Commands
 
-### `pk_synthesize` — orient before any investigation
+### `pk synthesize` — orient before any investigation
 
-```
-pk_synthesize({ sessionStart: true })                          # open questions + accepted decisions + active notes
-pk_synthesize({ query: "auth flow" })                         # ranked context for a topic
-pk_synthesize({ query: "auth", type: "decision", limit: 5 })
+```bash
+pk synthesize --session-start            # open questions + accepted decisions + active notes
+pk synthesize "auth flow"                # ranked context for a topic
+pk synthesize "auth" --type decision --limit 5
 ```
 
-Returns formatted markdown with title, type, status, tags, and an excerpt per note. Use `sessionStart: true` at the start of every session.
+Returns formatted markdown with title, type, status, tags, and an excerpt per note. Run `--session-start` at the start of every session.
 
-### `pk_search` — locate notes by content
+### `pk search` — locate notes by content
 
-```
-pk_search({ query: "database schema" })
-pk_search({ query: "api", type: "question", status: "open" })
-pk_search({ query: "deploy", tag: "infra", limit: 5 })
+```bash
+pk search "database schema"
+pk search "api" --type question --status open
+pk search "deploy" --tag infra --limit 5
 ```
 
-Returns `[{ path, type, status, title, tags, snippet }]`. Always call before `pk_new` — duplicates erode trust faster than gaps do.
+Returns path, type, status, title, tags, and snippet per match. Always search before creating — duplicates erode trust faster than gaps do.
 
-### `pk_read` — full note body
+### `pk read` — full note body
 
-```
-pk_read({ path: "/abs/path/returned/by/pk_search" })
+```bash
+pk read /abs/path/from/search
 ```
 
-Returns complete file contents including frontmatter. Use paths from `pk_search` or `pk_synthesize` output.
+Returns complete file contents including frontmatter. Use paths from `pk search` or `pk synthesize` output.
 
-### `pk_new` — create a typed note skeleton
+### `pk new` — create a typed note skeleton
 
-```
-pk_new({ type: "note", title: "Auth token expiry behaviour", tags: "auth,security" })
-pk_new({ type: "decision", title: "Use JWT over sessions" })
-pk_new({ type: "question", title: "Should we rate-limit the search endpoint?" })
-pk_new({ type: "source", title: "Meeting notes 2024-06-01" })
+```bash
+pk new note "Auth token expiry behaviour" --tags auth,security
+pk new decision "Use JWT over sessions"
+pk new question "Should we rate-limit the search endpoint?"
+pk new source "Meeting notes 2024-06-01"
 ```
 
-Returns the absolute path. Frontmatter (id, dates, status, tags as YAML array) is generated automatically from your inputs — you don't edit frontmatter after creation. After receiving the path: call `pk_read` to see the skeleton, then use your standard file Edit tool to fill in the required sections.
+Prints the absolute path. Frontmatter (id, dates, status, tags) is generated automatically — don't edit frontmatter after creation. After receiving the path: `pk read` to see the skeleton, then edit the file to fill in the required sections.
 
 **Required sections by type:**
 - `note` → `## Summary`, `## Details`, `## Evidence`, `## Related`
@@ -58,23 +58,58 @@ Returns the absolute path. Frontmatter (id, dates, status, tags as YAML array) i
 
 **`source` vs `note`:** `source` = raw/provenance-heavy input (meeting notes, transcripts, external docs, unprocessed data). `note` = stable synthesised fact or constraint you've derived. When synthesising across multiple sources into one insight: create a `note` and put source paths in `## Evidence`.
 
-### `pk_lint` — validate before committing
+### `pk lint` — validate before committing
+
+```bash
+pk lint              # all notes
+pk lint path1 path2  # specific notes
+```
+
+**Errors block commits** (missing frontmatter, duplicate id, wrong folder, missing required sections). **Warnings are advisory** (empty tags, note too long) — fix when practical.
+
+### `pk history` — view knowledge operations
+
+```bash
+pk history                                    # last 20 operations
+pk history --limit 50 --type commits           # only CUD operations
+pk history --filter-type decision              # only decisions
+pk history --filter-tag important              # only tagged 'important'
+pk history --filter-operation update           # only updates
+```
+
+### `pk delete` — delete a note
 
+```bash
+pk delete /abs/path/to/note.md --yes
 ```
-pk_lint({})
+
+Deletes and commits. `--yes` skips confirmation (required in non-interactive mode).
+
+### `pk vocab` — list tags by frequency
+
+```bash
+pk vocab
+```
+
+Useful for orienting before searching.
+
+### `pk edit` — edit a note in $EDITOR
+
+```bash
+pk edit /abs/path/to/note.md
 ```
 
-**Errors block commits** (missing frontmatter, duplicate id, wrong folder, missing required sections, broken links). **Warnings are advisory** (empty tags, note too long, source marked processed with no extracted items) — fix when practical, not required to commit.
+Opens the note in `$EDITOR`, validates after save, commits changes. For agents: use `pk read` + file edit + `pk lint` instead.
 
 ### Status transitions
 
-No MCP tool for status changes. Use your file Edit tool directly on the frontmatter, fill in the resolution section, then lint.
+No command for status changes. Edit the frontmatter `status` field directly, then `pk lint` to validate.
 
-**MANDATORY READ `references/knowledge-model.md`** when: creating a note type you haven't used before, unsure which folder a type belongs in, validating frontmatter fields, or unsure which status values are valid for a given type. (Read with your standard file Read tool — these are local skill files, not MCP-accessible.)
+**MANDATORY READ `references/knowledge-model.md`** when: creating a note type you haven't used before, unsure which folder a type belongs in, validating frontmatter fields, or unsure which status values are valid for a given type.
 
 ## NEVER
 
-- **NEVER skip `pk_search` before `pk_new`**
+- **NEVER skip `pk search` before `pk new`**
   **Why:** Duplicates silently fragment knowledge — two notes on the same topic never get reconciled, and future searches return noise.
   **Instead:** Search first; update the existing note if found, or create and link if genuinely different.
 
@@ -86,6 +121,6 @@ No MCP tool for status changes. Use your file Edit tool directly on the frontmat
   **Why:** Silent overwrites destroy the rationale trail — you lose why the old claim existed.
   **Instead:** Create a new note explaining the conflict, link both, and use `status: superseded` on the old one.
 
-- **NEVER commit when `pk_lint` returns errors or unrelated files are staged**
+- **NEVER commit when `pk lint` returns errors or unrelated files are staged**
   **Why:** Lint errors mean required structure is broken; mixed commits make knowledge changes unauditable.
   **Instead:** Fix errors, unstage unrelated files, then commit.