paput-mcp 4.2.6 → 4.2.9

package/README.md

@@ -121,7 +121,7 @@ npx -y paput-mcp setup-ai --codex-only
 
 Generated skills:
 
-- `paput-init` - Initialize PaPut usage and inspect unprocessed sessions from local-file-capable AI clients.
+- `paput-harvest` - Harvest reusable knowledge from past local sessions in local-file-capable AI clients. Safe to run repeatedly; skips already-processed sessions.
 - `paput-capture` - Extract reusable knowledge candidates from the current conversation or a specified topic and add them to pending.
 - `paput-save` - Review pending candidates first, then save only candidates explicitly approved by the user.
 - `paput-analyze-discard-policy` - Analyze discarded candidates and save a capture policy used by future captures.
@@ -268,7 +268,8 @@ Remote HTTP MCP.
 
 PaPut MCP no longer reads local Claude/Codex session files as MCP tools. When
 using Claude Code, Codex, or another AI client with local file access, run the
-installed `paput-init` skill. The AI client reads its own session files, extracts
+installed `paput-harvest` skill (safe to run repeatedly; it skips
+already-processed sessions). The AI client reads its own session files, extracts
 reusable knowledge, and submits only the resulting candidates and processed
 session markers through PaPut MCP.
 

package/dist/cli/skills/paput-capture/SKILL.md

@@ -53,8 +53,24 @@ Guidance:
 
 - Capture candidates are reusable decision criteria, procedures, or principles, so prefer `decision` / `operation` / `principle` when they fit; use `knowledge` for commodity technical know-how.
 - `decision` / `operation` / `principle` are the primary material for the public AI summary; `knowledge` usually is not.
+- Tagging review — do not under-label. The default failure mode is dropping a judgment memo into `knowledge` and missing `decision` / `operation` / `principle`; this is a main reason the `principle` axis stays thin. Consider the durable three FIRST and use `knowledge` only when none genuinely fit. Quick catches: a stated reason for choosing or avoiding an option → `decision`; an operating practice (how you measure, review, run, or verify) → `operation`; a generalized stance one level above a single decision → `principle`. Before finalizing `memo_type_keys`, re-read the candidate once and ask "is there a judgment here that I labeled as mere knowledge?". Do not over-correct either: `principle` needs an explicitly generalized stance, not a one-off opinion — keep it honest against the Quality Bar.
+- AI-collaboration practices and stances belong here, not in the reject pile: how you structure a task or spec for an AI, your review discipline for AI-generated changes, where you verify versus trust AI output, when you delegate versus do it yourself. Capture the reusable practice as `operation` or the stated stance as `principle` — generalized so it would hold with a different AI tool, on a different project, for someone else to learn. This is the scarcest, most durable axis; do not drop it as workflow chatter.
 - Leaving a candidate unclassified (no type) is allowed, but classifying it improves analysis and the public profile. Do not force a type when none fits.
 
+## Eliciting scarce operating practices (eval / observability)
+
+`operation` is a primary public-summary axis, but its eval / observability / measurement part is the scarcest and most easily lost — it surfaces as "how the work was measured and watched", not as a deliverable, so generic free-form capture tends to miss it or leave thin, ad-hoc candidates. When the conversation touched measurement, evaluation, monitoring, alerting, test strategy, SLO / SLI, threshold or pass-fail tuning, or incident review, do not let it pass as a work log: actively draw out the reusable practice and capture it as `operation` (or `principle` for a stated stance, `decision` for an adopt/reject criterion).
+
+Draw out only what fits the conversation — do not interrogate:
+
+- What was measured, and why that signal rather than another?
+- How was signal separated from noise?
+- How was the threshold / pass-fail decided — by feel, or by offline evaluation?
+- What is watched in production, and where were alerts placed, and why there?
+- What did a failure or false positive teach, and how did it change the judgment?
+
+Generalize one level above the project: drop service, metric, and dashboard names; keep the criterion, the rationale, and the verification method. A candidate here must carry at least one of measurement target + why, threshold rationale, or verification method — a bare "added monitoring" or "wrote tests" is a work log, not knowledge. This is a lens for capturing the user's methodology, not a feature: do not turn PaPut into an eval or monitoring tool.
+
 ## Quality Bar
 
 Before adding a candidate, make sure the body preserves enough reasoning for future reuse. A good candidate is not just a conclusion; it should include the relevant problem context, decision criteria, applicability conditions, tradeoffs, pitfalls, operational guidance, or verification method.
@@ -73,7 +89,7 @@ Prefer generalized but concrete writing:
 Do not add these to pending:
 
 - Project-specific specifications, screen names, button names, business workflows, operational rules, or local context.
-- Personal workflow notes about PRs, GitHub, Codex, Claude, AI review, editors, or OS operations.
+- One-off tool mechanics or configuration: editor / OS / CLI settings, keybindings, which button was clicked, model- or version-specific quirks, project-specific CI wiring, or anecdotes about a single session (for example, "the AI got confused here"). These are commodity even when they mention AI tools — capture the reusable practice or stance instead, not the mechanics. Reusable AI-collaboration practices and stances ARE worth capturing (see the AI-collaboration note under Memo Type); do not discard them as workflow chatter.
 - Content that third parties cannot understand from the title and body alone.
 - Rejected designs, anecdotes, work logs, impressions, or decision histories without reusable guidance.
 - Content semantically close to existing memos or pending candidates.

package/dist/cli/skills/paput-harvest/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: paput-harvest
+description: Use this to harvest reusable knowledge from past local Claude/Codex sessions when the AI client can read local files. Safe to run repeatedly — it skips already-processed sessions and only reviews new ones — so use it both for first-time onboarding and for periodic catch-up. Pay special attention to AI-collaboration practices and stances (operation / principle), the scarce, durable axis.
+---
+
+# PaPut Harvest
+
+Harvest reusable knowledge from past local AI sessions into pending candidates.
+
+This skill is for local-file-capable AI clients such as Claude Code or Codex.
+PaPut MCP does not read local session files. The AI client reads the session
+files directly, then uses PaPut MCP only to check processed-session markers and
+add or mark reviewed sessions.
+
+Run it whenever you want — it is idempotent. It checks which sessions are already
+processed and reviews only the new ones, so the first run doubles as onboarding
+(nothing is processed yet, so it surveys your history) and later runs are
+periodic catch-up. There is no separate "init" step.
+
+## Steps
+
+1. Get processed sessions with `paput_list_processed_sessions`.
+2. Find local session files the AI client can access:
+   - Claude: `~/.claude/projects/**/*.jsonl`
+   - Codex: `~/.codex/sessions/**/*.jsonl`
+3. For each file, derive:
+   - `source`: `claude` or `codex`
+   - `session_id`: file basename without `.jsonl`
+   - `source_session_updated_at`: file modified time in ISO 8601 format
+4. Skip sessions already returned by `paput_list_processed_sessions`.
+5. Report the count and a short summary of unprocessed sessions to the user.
+6. Only when the user wants it, read the relevant session transcript directly
+   from the JSONL file and create candidates that meet the extraction criteria.
+   While reading, actively look for the AI-collaboration axis (see Extraction
+   Criteria) in addition to ordinary technical knowledge — it is easy to miss
+   because it shows up as how the work was directed, not as the work itself.
+7. Before adding candidates with `paput_add_knowledge_candidates`, check that
+   they do not contain project-specific specifications, implementation details,
+   operational rules, code, customer data, or secrets. Duplicate checks against
+   existing memos run automatically inside `paput_add_knowledge_candidates`
+   using semantic search.
+8. If reusable candidates exist, call `paput_add_knowledge_candidates` with
+   `source`, `session_id`, `source_session_updated_at`, and the candidates.
+   Set `memo_type_keys` on each candidate (see Memo Type below); classify
+   AI-collaboration practices as `operation` and stances as `principle`.
+9. If the session was reviewed but no candidates should be added, call
+   `paput_mark_processed_session` with `source`, `session_id`, and
+   `source_session_updated_at`.
+10. Briefly report added candidates, duplicates, rejected candidates, and
+    sessions marked as processed.
+
+## JSONL Parsing Guide
+
+When reading session files, extract user and assistant messages only.
+
+Claude session lines commonly have:
+
+- `type`: `user` or `assistant`
+- `message.role`: `user` or `assistant`
+- `message.content`: string or content blocks such as `{ "type": "text", "text": "..." }`
+- `cwd`, `message.cwd`, or `payload.cwd` may exist as local context, but do not
+  save local paths or project-specific details as knowledge.
+
+Codex session lines commonly have:
+
+- `type`: `response_item`
+- `payload.type`: `message`
+- `payload.role`: `user` or `assistant`
+- `payload.content`: content blocks such as `input_text`, `output_text`, or `text`
+- `payload.cwd` may exist as local context, but do not save local paths or
+  project-specific details as knowledge.
+
+Read only what is needed. If the session is large, inspect metadata and relevant
+tail sections first, then ask before reading more.
+
+## Extraction Criteria
+
+Only add technical knowledge, decision criteria, and procedures that can be reused in other projects.
+
+### Capture the AI-collaboration axis
+
+Reusable AI-collaboration practices and stances are first-class material here —
+they are the scarcest, most durable axis and are easy to discard by mistake.
+Capture them as `operation` (practice) or `principle` (stance). Examples:
+
+- How you structure a task or spec so an AI implements it correctly.
+- Your review discipline for AI-generated changes — where you always verify
+  versus where you trust the output.
+- When you delegate to an AI versus do it yourself.
+- How you decompose work for parallel agents, or recover when an AI goes wrong.
+
+The test: would this still hold with a different AI tool, on a different
+project, for someone else to learn? If yes, capture it as `operation` or
+`principle`, generalized one level above the specific session. If it is only
+about this tool's mechanics or this one session's events, exclude it.
+
+### Capture the eval / observability axis
+
+Eval, observability, and measurement practices are another scarce, durable
+`operation` sub-axis that is easy to lose — they show up as how the work was
+measured and watched, not as the work itself. When a session touched
+measurement, evaluation, monitoring, alerting, test strategy, SLO / SLI,
+threshold or pass-fail tuning, or incident review, capture the reusable practice
+as `operation` (or `principle` for a stance, `decision` for an adopt/reject
+criterion). Look for:
+
+- What was measured and why that signal; how signal was separated from noise.
+- How a threshold or pass-fail was decided — by feel or by offline evaluation.
+- What is watched in production and where alerts sit, and why there.
+- What a failure or false positive changed in the judgment.
+
+Generalize above the project (drop service / metric / dashboard names, keep the
+criterion and verification). A bare "added monitoring" or "wrote tests" with no
+rationale or verification is a work log — exclude it. This is a lens for
+capturing methodology, not a reason to log routine test/monitoring chores.
+
+### Do not add these to pending
+
+- Project-specific specifications, screen names, button names, business workflows, operational rules, or local context.
+- One-off tool mechanics or configuration: editor / OS / CLI settings, keybindings, which button was clicked, model- or version-specific quirks, project-specific CI wiring, or anecdotes about a single session (for example, "the AI got confused here"). These are commodity even when they mention AI tools — capture the reusable practice or stance instead, not the mechanics.
+- Content that third parties cannot understand from the title and body alone.
+- Rejected designs, anecdotes, work logs, impressions, or decision histories without reusable guidance.
+- Content semantically close to existing memos or pending candidates.
+- Generic security, authorization, or tenant-isolation notes when similar knowledge already exists.
+- Code fragments or project-specific naming that has not been generalized.
+
+When unsure, do not add the candidate. Report that there is no knowledge to save or that the candidate was rejected.
+
+## Memo Type
+
+Classify each candidate with one or more memo types via `memo_type_keys`:
+
+- `decision`: reusable judgment criteria independent of any project.
+- `operation`: operating practices — observability, eval, testing, review, and how you direct and verify AI collaboration.
+- `principle`: a stance you have explicitly stated, generalized above individual decisions, including stances on how to work with AI.
+- `knowledge`: commodity technical know-how, usage, or implementation knowledge.
+
+`decision` / `operation` / `principle` are the primary material for the public
+AI summary and the principle synthesizer; `knowledge` usually is not. Prefer the
+durable types when they fit, and do not force a type when none does.
+
+Tagging review — do not under-label. The default failure mode is dropping a
+judgment memo into `knowledge` and missing `decision` / `operation` /
+`principle`; this is a main reason the `principle` axis stays thin. Consider the
+durable three FIRST and use `knowledge` only when none genuinely fit. Quick
+catches: a stated reason for choosing or avoiding an option → `decision`; an
+operating practice (how you measure, review, run, or verify) → `operation`; a
+generalized stance one level above a single decision → `principle`. Before
+finalizing `memo_type_keys`, re-read the candidate once and ask whether there is
+a judgment you labeled as mere knowledge. Do not over-correct: `principle` needs
+an explicitly generalized stance, not a one-off opinion.
+
+## Notes
+
+- Do not save directly to PaPut.
+- Add candidates to the API-backed pending queue first.
+- `paput_add_knowledge_candidates` marks the source session as processed when candidates are submitted.
+- Use `paput_mark_processed_session` after reviewing a session that produces no candidates.
+- Report duplicates or similar memos when found.
+- Prefer high-quality pending candidates over increasing the pending count.

package/docs/privacy-policy.md

@@ -39,7 +39,7 @@ Remote MCP connections use OAuth. PaPut issues tokens after you sign in and appr
 Pending candidates, discarded candidate metadata, processed AI session markers,
 and capture policies are stored in PaPut API storage, not under `~/.paput`.
 PaPut MCP does not read local Claude/Codex session files. When you use
-`paput-init` in a local-file-capable client such as Claude Code or Codex, that
+`paput-harvest` in a local-file-capable client such as Claude Code or Codex, that
 client may read its own session files and submit only extracted candidates or
 processed-session markers to PaPut MCP.
 

package/docs/tools.md

@@ -5,8 +5,8 @@ PaPut MCP is a data-only MCP server. It exposes tools and resources for PaPut da
 Remote HTTP mode exposes API-backed PaPut tools. Pending candidates, processed
 session markers, and capture policies are stored by the PaPut API. PaPut MCP
 does not expose tools that read local Claude/Codex session files; local-file-
-capable clients can read those files themselves through the `paput-init` skill
-workflow and then submit extracted candidates through MCP.
+capable clients can read those files themselves through the `paput-harvest`
+skill workflow and then submit extracted candidates through MCP.
 
 ## Confirmation Policy
 
@@ -184,5 +184,5 @@ The capture policy is not saved as a PaPut memo. It is stored by the PaPut API
 and is available through Remote HTTP MCP.
 
 For past-session import, a local-file-capable AI client should read its own
-Claude/Codex session files through the `paput-init` skill, then call
+Claude/Codex session files through the `paput-harvest` skill, then call
 `paput_add_knowledge_candidates` or `paput_mark_processed_session`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paput-mcp",
-  "version": "4.2.6",
+  "version": "4.2.9",
   "description": "PaPut MCP Server",
   "main": "dist/index.js",
   "type": "module",

package/dist/cli/skills/paput-init/SKILL.md

@@ -1,89 +0,0 @@
----
-name: paput-init
-description: Use this to initialize PaPut usage and inspect unprocessed local Claude/Codex sessions when the AI client can read local files.
----
-
-# PaPut Init
-
-Initialize PaPut knowledge capture from past local AI sessions.
-
-This skill is for local-file-capable AI clients such as Claude Code or Codex.
-PaPut MCP does not read local session files. The AI client should read the
-session files directly, then use PaPut MCP only to check processed-session
-markers and add or mark reviewed sessions.
-
-## Steps
-
-1. Get processed sessions with `paput_list_processed_sessions`.
-2. Find local session files the AI client can access:
-   - Claude: `~/.claude/projects/**/*.jsonl`
-   - Codex: `~/.codex/sessions/**/*.jsonl`
-3. For each file, derive:
-   - `source`: `claude` or `codex`
-   - `session_id`: file basename without `.jsonl`
-   - `source_session_updated_at`: file modified time in ISO 8601 format
-4. Skip sessions already returned by `paput_list_processed_sessions`.
-5. Report the count and a short summary of unprocessed sessions to the user.
-6. Only when the user wants it, read the relevant session transcript directly
-   from the JSONL file and create candidates that meet the extraction criteria.
-7. Before adding candidates with `paput_add_knowledge_candidates`, check that
-   they do not contain project-specific specifications, implementation details,
-   operational rules, code, customer data, or secrets. Duplicate checks against
-   existing memos run automatically inside `paput_add_knowledge_candidates`
-   using semantic search.
-8. If reusable candidates exist, call `paput_add_knowledge_candidates` with
-   `source`, `session_id`, `source_session_updated_at`, and the candidates.
-9. If the session was reviewed but no candidates should be added, call
-   `paput_mark_processed_session` with `source`, `session_id`, and
-   `source_session_updated_at`.
-10. Briefly report added candidates, duplicates, rejected candidates, and
-    sessions marked as processed.
-
-## JSONL Parsing Guide
-
-When reading session files, extract user and assistant messages only.
-
-Claude session lines commonly have:
-
-- `type`: `user` or `assistant`
-- `message.role`: `user` or `assistant`
-- `message.content`: string or content blocks such as `{ "type": "text", "text": "..." }`
-- `cwd`, `message.cwd`, or `payload.cwd` may exist as local context, but do not
-  save local paths or project-specific details as knowledge.
-
-Codex session lines commonly have:
-
-- `type`: `response_item`
-- `payload.type`: `message`
-- `payload.role`: `user` or `assistant`
-- `payload.content`: content blocks such as `input_text`, `output_text`, or `text`
-- `payload.cwd` may exist as local context, but do not save local paths or
-  project-specific details as knowledge.
-
-Read only what is needed. If the session is large, inspect metadata and relevant
-tail sections first, then ask before reading more.
-
-## Extraction Criteria
-
-Only add technical knowledge, decision criteria, and procedures that can be reused in other projects.
-
-Do not add these to pending:
-
-- Project-specific specifications, screen names, button names, business workflows, operational rules, or local context.
-- Personal workflow notes about PRs, GitHub, Codex, Claude, AI review, editors, or OS operations.
-- Content that third parties cannot understand from the title and body alone.
-- Rejected designs, anecdotes, work logs, impressions, or decision histories without reusable guidance.
-- Content semantically close to existing memos or pending candidates.
-- Generic security, authorization, or tenant-isolation notes when similar knowledge already exists.
-- Code fragments or project-specific naming that has not been generalized.
-
-When unsure, do not add the candidate. Report that there is no knowledge to save or that the candidate was rejected.
-
-## Notes
-
-- Do not save directly to PaPut.
-- Add candidates to the API-backed pending queue first.
-- `paput_add_knowledge_candidates` marks the source session as processed when candidates are submitted.
-- Use `paput_mark_processed_session` after reviewing a session that produces no candidates.
-- Report duplicates or similar memos when found.
-- Prefer high-quality pending candidates over increasing the pending count.