skillwiki 0.9.60 → 0.9.62

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. package/dist/{chunk-FU462DVS.js → chunk-2PENIQ3A.js} +1181 -518
  2. package/dist/cli.js +994 -438
  3. package/dist/skillwiki-mcp.js +1 -1
  4. package/package.json +1 -1
  5. package/skills/.claude-plugin/plugin.json +1 -1
  6. package/skills/.codex-plugin/plugin.json +1 -1
  7. package/skills/README.md +6 -0
  8. package/skills/agents/wiki-ingest.md +30 -37
  9. package/skills/agents/wiki-query.md +13 -3
  10. package/skills/package.json +1 -1
  11. package/skills/skills/using-skillwiki/SKILL.md +16 -1
  12. package/skills/skills/wiki-ingest/SKILL.md +23 -27
  13. package/skills/skills/wiki-query/SKILL.md +11 -2
  14. package/skills/using-skillwiki/SKILL.md +16 -1
  15. package/skills/wiki-ingest/SKILL.md +23 -27
  16. package/skills/wiki-query/SKILL.md +11 -2
package/dist/skillwiki-mcp.js CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  runSkillwikiMcpStdio
4
- } from "./chunk-FU462DVS.js";
4
+ } from "./chunk-2PENIQ3A.js";
5
5
  import "./chunk-7I2TPIV5.js";
6
6
 
7
7
  // src/mcp-entry.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "skillwiki",
3
- "version": "0.9.60",
3
+ "version": "0.9.62",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "skillwiki": "dist/cli.js",
package/skills/.claude-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "skillwiki",
3
- "version": "0.9.60",
3
+ "version": "0.9.62",
4
4
  "skills": "./",
5
5
  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
6
6
  "author": {
package/skills/.codex-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "skillwiki",
3
- "version": "0.9.60",
3
+ "version": "0.9.62",
4
4
  "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
5
5
  "author": {
6
6
  "name": "karlorz",
package/skills/README.md CHANGED
@@ -5,6 +5,12 @@ or the Claude/Codex/Antigravity plugin packaging paths.
5
5
 
6
6
  Current package inventory: **18 skills**.
7
7
 
8
+ Publication policy: new or updated typed-knowledge and meta pages must use
9
+ `skillwiki page publish` from a temporary draft, inspect its dry-run, and add
10
+ `--write` only after the preview succeeds. Do not directly publish the final
11
+ typed path or separately edit its index/log entries; immutable raw sources and
12
+ non-typed project work retain their existing workflows.
13
+
8
14
  | Namespace | Skills |
9
15
  |---|---|
10
16
  | `wiki-*` | `wiki-init`, `wiki-ingest`, `wiki-query`, `wiki-lint`, `wiki-crystallize`, `wiki-audit`, `wiki-archive`, `wiki-reingest`, `wiki-adapter-prd`, `wiki-add-task`, `wiki-sync`, `wiki-canvas`, `wiki-gate-plan-mode` |
package/skills/agents/wiki-ingest.md CHANGED
@@ -6,74 +6,67 @@ color: green
6
6
  tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
7
7
  ---
8
8
 
9
- You are a vault ingestion specialist converting source material (URLs, files, text) into typed-knowledge pages with raw provenance. You follow the N6/N7/N8 pipeline: guard → fetch → hash → generate → validate → write. You operate autonomously during maintenance cycles.
9
+ You are a vault ingestion specialist converting source material (URLs and readable local files) into typed-knowledge pages with raw provenance. You follow the N6/N7/N8 pipeline: guard → fetch → hash → generate → validate → write. You operate autonomously during maintenance cycles.
10
10
 
11
11
  ## When to invoke
12
12
 
13
13
  - **URL ingestion.** Dev-loop spawns you with URLs to fetch and convert to knowledge pages.
14
14
  - **File ingestion.** Local files need to be captured as raw sources and distilled into concept pages.
15
- - **Batch ingestion.** Multiple sources to process before a single index/log update.
15
+ - **Batch ingestion.** Multiple sources to process through deterministic raw capture and shared publication.
16
16
  - **Raw promotion.** A raw/transcripts/ capture is ready for promotion to a typed-knowledge page.
17
17
 
18
18
  **Your Core Responsibilities:**
19
19
  1. Guard: run `skillwiki fetch-guard <url>` for URL sources
20
- 2. Fetch content and write raw file with sha256
21
- 3. Compose typed-knowledge page(s) with citations
22
- 4. Validate every page before writing index/log
23
- 5. Apply writes in order: raw → page(s) → index.md → log.md
20
+ 2. Stage pasted text as a readable external file before capture; `skillwiki ingest` does not accept literal text
21
+ 3. Capture each source through `skillwiki ingest`
22
+ 4. Let the shared publisher own typed-page, taxonomy, index, and structural-log writes
23
+ 5. Preserve raw-only recovery state when typed publication fails
24
24
 
25
25
  **Execution Process:**
26
26
 
27
27
  1. **Resolve vault and language.** Run `skillwiki path` and `skillwiki lang`.
28
28
  2. **Guard (URL sources).** For each URL: `skillwiki fetch-guard <url>`. If non-zero, STOP.
29
- 3. **Fetch.** Fetch content.
30
- 4. **Sensitive content guard.** Before writing or filing any vault page, scan the source and generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact generated prose before writing. If the source itself must remain raw and contains a live secret, STOP instead of preserving it.
31
- 5. **Write raw and hash.** Write raw file at `raw/articles/<slug>.md` with proper frontmatter (`source_url`, `ingested`, `sha256` placeholder). Run `skillwiki hash <raw-file>` and embed the result in `sha256:`.
32
- 6. **Generate page(s).** Compose typed-knowledge pages with:
33
- - Proper frontmatter (`title`, `type`, `tags` from SCHEMA.md taxonomy, `provenance`, `sources`)
34
- - `## TL;DR` as first section — 1–3 bullet summary
35
- - `^[raw/...]` citations for every factual claim
36
- - Mermaid diagram if tagged `architecture` or explaining workflows
37
- - `confidence: low` if only one source cited
38
- - For generated `comparisons/` pages or evaluation-style `queries/` pages, end with:
39
- ```markdown
40
- ## Decision Closeout
41
-
42
- Disposition: no-op | concept | ADR | work-item | evidence-needed
43
- Reason: ...
44
- Follow-up: ...
45
- ```
46
- Use exactly one disposition. This is a prompt convention, not a validator rule.
47
- 7. **Validate.** For each page: `skillwiki validate <page>`. If any non-zero, fix issues and re-validate. Do NOT proceed until all pages pass.
48
- 8. **Apply writes in order:** raw file(s) → page(s) → update `index.md` → append `log.md`.
29
+ 3. **Stage pasted text as a file source.** `skillwiki ingest` accepts a readable local source file or HTTP(S) URL; it does **not** accept literal pasted text. For a paste, stage the exact text in a temporary file outside the vault, then pass its path to the normal command:
30
+ ```bash
31
+ skillwiki ingest <staged-paste-path> \
32
+ --vault <resolved-vault> \
33
+ --type <entity|concept|comparison|query> \
34
+ --title "<title>" \
35
+ --tags "<tag1,tag2>" \
36
+ --provenance <research|project>
37
+ ```
38
+ Record the staged path and exact command inputs before execution. If ingestion or typed-page publication fails, retain the staged source and exact command inputs for retry. Remove the staged file only after `skillwiki ingest` exits 0 after typed-page publication; confirm the non-dry-run result reports its raw path, typed path, and publisher operation. Do not stage pasted text inside the vault.
39
+ 4. **Sensitive content guard.** Before filing any vault page, scan the source and generated inputs for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact generated prose before writing. If the source itself must remain raw and contains a live secret, STOP instead of preserving it.
40
+ 5. **Feature-detect publication.** Run `skillwiki page publish --help`. If unavailable, fail closed and leave typed output unpublished; update the active SkillWiki CLI/plugin channel first.
41
+ 6. **Ingest and publish.** Use `skillwiki ingest` for deterministic source capture and typed-page publication. The command writes an immutable raw source first and delegates the typed page, taxonomy, index, and structural log entry to the shared page publisher. Supply the resolved vault, type, title, tags, and provenance through the command options.
42
+ 7. **Recovery.** Never create the final typed page or edit index.md/log.md directly. A raw-only result after publication failure is valid recovery state. Keep the exact command inputs and retry; do not delete or overwrite the raw source.
49
43
 
50
44
  ### Batch mode
51
45
  When multiple sources are provided:
52
- - Execute steps 2–6 per source individually
53
- - Accumulate all raw files and pages in memory
54
- - Fail fast: if any page fails validation, STOP and report all failures
55
- - Deduplicate: check sha256 against existing vault raw sources
56
- - Single index/log update after ALL sources validate
57
- - Report progress after each source validates
46
+ - Execute steps 2–7 per source individually, using one `skillwiki ingest` command per source
47
+ - Fail fast: if an ingest command returns nonzero, STOP and report the retained raw-only state, if any, with its exact retry inputs
48
+ - Let `skillwiki ingest` preserve immutable raw capture and skip sources whose content is already present
49
+ - Report progress after each source completes, including the raw path, typed path or recovery state, and publisher operation ID
58
50
 
59
51
  **Output Format:**
60
52
  Return:
61
53
  - Sources processed (count)
54
+ - Exact `skillwiki ingest` inputs
62
55
  - Raw files written (paths + sha256)
63
- - Pages generated (paths + types)
64
- - Validation results
65
- - Index.md and log.md entries appended
56
+ - Typed pages published (paths + types) or raw-only recovery state
57
+ - Publisher operation IDs and results
66
58
 
67
59
  **Stop Conditions:**
68
60
  - `fetch-guard` non-zero
69
61
  - Fetch timeout or size limit exceeded
70
- - `validate` non-zero on any page (after retry)
62
+ - `skillwiki page publish --help` is unavailable
63
+ - `skillwiki ingest` returns nonzero; retain any raw-only result for retry
71
64
  - sha256 already exists in vault (skip, don't duplicate)
72
65
  - Source or generated content contains unredacted live credentials or other authenticating secrets
73
66
 
74
67
  **Forbidden:**
75
68
  - Skipping `fetch-guard` for URL sources
76
- - Updating index/log before all pages validate
69
+ - Creating a final typed page or editing index.md/log.md directly
77
70
  - Modifying existing raw files (N9)
78
71
  - Writing `[[wikilinks]]` to nonexistent pages — verify first
79
72
  - Writing raw ephemeral data to cloud-mounted wiki paths
package/skills/agents/wiki-query.md CHANGED
@@ -35,7 +35,15 @@ You are a vault search and synthesis specialist using E2 4-signal ranking to fin
35
35
  6. **Read top candidates.** Read frontmatter + body of highest-scored pages.
36
36
  7. **Synthesize answer.** Compose with explicit citations to candidate pages using `^[page-path]` markers.
37
37
  8. **Sensitive content guard.** Before filing a query or comparison page, scan the generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact before writing. If the answer depends on preserving a live secret, STOP and ask for a redacted source or explicit rotation/remediation direction.
38
- 9. **Optional file.** If the task asks to persist: write to `queries/<slug>.md` or `comparisons/<slug>.md` with full frontmatter, validate, then update `index.md` → `log.md`. If the filed page is a research/evaluation answer, recommendation, or comparison, end it with:
38
+ 9. **Optional file.** If the task asks to persist, first run `skillwiki page publish --help`. If it is unavailable, fail closed and leave the result unpublished. Otherwise:
39
+ 1. Resolve the vault and create a temporary directory outside the vault.
40
+ 2. Write the complete query/comparison page to `<temp>/page.md`, including final frontmatter, citations, Sources footer, and Decision Closeout.
41
+ 3. Run `skillwiki page publish <temp>/page.md <vault> --target queries/<slug>.md` (or `comparisons/<slug>.md`) and inspect the dry-run.
42
+ 4. Run the identical command with `--write` only when dry-run succeeds.
43
+ 5. On any nonzero result, retain the draft path and STOP; do not edit the final target, index.md, or log.md directly.
44
+ 6. Remove the temporary directory only after the publisher returns complete success.
45
+
46
+ If the filed page is a research/evaluation answer, recommendation, or comparison, end it with:
39
47
  ```markdown
40
48
  ## Decision Closeout
41
49
 
@@ -54,15 +62,17 @@ Return:
54
62
  - Top candidate pages (ranked, with scores)
55
63
  - Synthesized answer with citations
56
64
  - Whether result was filed (and path if so)
57
- - Log entries appended
65
+ - Publisher result (target, operation ID, or retained draft path on failure)
58
66
 
59
67
  **Stop Conditions:**
60
68
  - Zero matching pages found
61
69
  - `skillwiki path` returns NO_VAULT_CONFIGURED
62
70
  - Generated filed content contains unredacted live credentials or other authenticating secrets
71
+ - `skillwiki page publish --help` is unavailable
63
72
 
64
73
  **Forbidden:**
65
- - Filing without `validate` passing
74
+ - Filing without the `skillwiki page publish` dry-run passing
75
+ - Directly creating a final typed page or separately editing `index.md` or `log.md` for its publication
66
76
  - Skipping graph refresh when graph.json is missing
67
77
  - Accepting wiki claims without filesystem verification
68
78
  - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault
package/skills/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skillwiki/skills",
3
- "version": "0.9.60",
3
+ "version": "0.9.62",
4
4
  "private": true,
5
5
  "files": [
6
6
  "wiki-*",
package/skills/skills/using-skillwiki/SKILL.md CHANGED
@@ -59,6 +59,21 @@ sha256: # computed by skillwiki hash over body bytes after closing ---
59
59
  ## Sensitive Content Policy
60
60
  Vault content must not contain live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets. This includes development-only and local-only credentials. Redact values before filing using `[REDACTED:<kind>]` or `[REDACTED:<kind>:<fingerprint>]`. If a source contains live secrets, stop and ask for a redacted source or explicit rotation/remediation direction; do not preserve the secret in `raw/`.
61
61
 
62
+ ## Typed-Page Publication Contract
63
+
64
+ All new or updated typed-knowledge and meta pages MUST be published through
65
+ `skillwiki page publish`. Compose the complete page at an unpublished temporary
66
+ path, run publisher dry-run, then run the same command with `--write`.
67
+
68
+ - Do not directly create or edit the final typed-page path.
69
+ - Do not directly update `index.md` or append the page's structural log entry.
70
+ - If `skillwiki page publish --help` is unavailable, fail closed and leave the
71
+ result unpublished; update the active SkillWiki CLI/plugin channel first.
72
+ - `skillwiki validate --apply` is a legacy repair/compatibility path, not the
73
+ new-page publication path.
74
+ - Non-typed project work items and immutable raw sources keep their existing
75
+ workflows.
76
+
62
77
  ## Portable Source References
63
78
  The vault is shared across hosts, so host-local absolute paths are not durable source identity.
64
79
 
@@ -120,7 +135,7 @@ Use `prd_layer` + `prd_pipeline` from `.claude/dev-loop.config.md` as source of
120
135
 
121
136
  ## CLI Backbone
122
137
  All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, health reporting, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
123
- Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `fleet context`, `fleet validate`, `graph build`, `archive`, `drift`, `compound`, `tag-sync`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.
138
+ Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `fleet context`, `fleet validate`, `graph build`, `archive`, `drift`, `compound`, `tag-sync`, `tag reconcile`, `page publish`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.
124
139
  Run `skillwiki health <vault> --out /tmp/skillwiki-health.json --no-fail` for a bounded whole-system report that includes doctor, lint, vault-sync, query-readiness, source-freshness, risk flags, and self-check coverage. Run `skillwiki lint <vault> --summary` for lint-only bucket counts with capped examples and details commands. Run `skillwiki doctor` to diagnose setup/runtime issues only. Run `skillwiki config list` to see current configuration.
125
140
 
126
141
  ## Runtime Host Context and Fleet Freshness
package/skills/skills/wiki-ingest/SKILL.md CHANGED
@@ -14,29 +14,26 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
14
14
  2. `index.md`
15
15
  3. Last 20–30 entries of `log.md`
16
16
  4. (Project context only) `projects/{slug}/README.md` and last ~5 work-item logs.
17
- ## Steps (in order — N6, N7, N8)
17
+ ## Steps (in order — deterministic raw capture and shared publication)
18
18
  0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`. Use the resolved vault path for all writes; use the canonical language for all generated prose.
19
19
  1. **Guard.** For each URL: run `skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
20
20
  2. **Fetch.** Use `web_fetch` (or read local file) under Layer 2 controls (the CLI Layer 2 fetcher applies in tests; in skill runtime use `web_fetch` directly and treat any error as STOP).
21
21
  - **Portable local-source rule:** follow `using-skillwiki` → Portable Source References. Do not use `source_url: file:///...` as the canonical durable reference; prefer commit-pinned GitHub `blob/<commit>/<path>` when resolvable, else empty `source_url` plus portable repo-relative prose.
22
- 3. **Identity guard.** Before writing raw files, ensure the target raw filename/title, `source_url`, fetched H1/title, and early body subject agree. If `skillwiki ingest` reports `INGEST_VALIDATION_FAILED` with `source identity conflict`, STOP. Do not fix by renaming after the fact; choose the correct title/source pair or ask the user.
23
- 4. **Sensitive content guard.** Before writing or filing any vault page, scan the source and generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact generated prose before writing. If the source itself must remain raw and contains a live secret, STOP instead of preserving it.
24
- 5. **Hash.** Write the raw file (frontmatter + body). Run `skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
25
- 6. **Generate page(s).** Compose typed-knowledge page(s) with citations pre-attached (`^[raw/...]` markers). Every page MUST include:
26
- - `> **TL;DR:**` blockquote as the first content after the title heading — a one-sentence summary of the page's key takeaway (under 200 chars). See SCHEMA.md `## TL;DR Convention`.
27
- - For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
28
- For generated `comparisons/` pages or evaluation-style `queries/` pages, end the body with:
29
- ```markdown
30
- ## Decision Closeout
31
-
32
- Disposition: no-op | concept | ADR | work-item | evidence-needed
33
- Reason: ...
34
- Follow-up: ...
35
- ```
36
- Use exactly one disposition. Keep this as a prompt convention, not a validator rule.
37
- 7. **Validate.** For each generated page: run `skillwiki validate <page>`. If exit ≠ 0, STOP — do not write index/log.
38
- 8. **Apply writes in order.** raw → page(s) → `index.md` → `log.md`.
39
- 9. **Confidence flag.** If only one source is cited, set `confidence: low`.
22
+ 3. **Stage pasted text as a file source.** `skillwiki ingest` accepts a readable local source file or HTTP(S) URL; it does **not** accept literal pasted text. For a paste, stage the exact text in a temporary file outside the vault, then pass its path to the normal command:
23
+ ```bash
24
+ skillwiki ingest <staged-paste-path> \
25
+ --vault <resolved-vault> \
26
+ --type <entity|concept|comparison|query> \
27
+ --title "<title>" \
28
+ --tags "<tag1,tag2>" \
29
+ --provenance <research|project>
30
+ ```
31
+ Record the staged path and exact command inputs before execution. If ingestion or typed-page publication fails, retain the staged source and exact command inputs for retry. Remove the staged file only after `skillwiki ingest` exits 0 after typed-page publication; confirm the non-dry-run result reports its raw path, typed path, and publisher operation. Do not stage pasted text inside the vault.
32
+ 4. **Identity guard.** Before writing raw files, ensure the target raw filename/title, `source_url`, fetched H1/title, and early body subject agree. If `skillwiki ingest` reports `INGEST_VALIDATION_FAILED` with `source identity conflict`, STOP. Do not fix by renaming after the fact; choose the correct title/source pair or ask the user.
33
+ 5. **Sensitive content guard.** Before writing or filing any vault page, scan the source and generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact generated prose before writing. If the source itself must remain raw and contains a live secret, STOP instead of preserving it.
34
+ 6. **Feature-detect publication.** Run `skillwiki page publish --help`. If unavailable, fail closed and leave typed output unpublished; update the active SkillWiki CLI/plugin channel first.
35
+ 7. **Ingest and publish.** Use `skillwiki ingest` for deterministic source capture and typed-page publication. The command writes an immutable raw source first and delegates the typed page, taxonomy, index, and structural log entry to the shared page publisher. Supply the resolved vault, type, title, tags, and provenance through the command options.
36
+ 8. **Recovery.** Never create the final typed page or edit index.md/log.md directly. A raw-only result after publication failure is valid recovery state. Keep the exact command inputs and retry; do not delete or overwrite the raw source.
40
37
  ## Provenance defaults
41
38
  - Default `provenance: research`.
42
39
  - If cwd is inside `projects/{slug}/`, set `provenance: project` and add `provenance_projects: ["[[slug]]"]`.
@@ -50,20 +47,19 @@ Raw ephemeral data (market feeds, logs, transient JSON) must be written to the *
50
47
  - Fetch timeout / size limit exceeded.
51
48
  - `INGEST_VALIDATION_FAILED` with `source identity conflict`.
52
49
  - Source or generated content contains unredacted live credentials or other authenticating secrets.
53
- - `validate` non-zero on any page.
50
+ - `skillwiki page publish --help` is unavailable.
51
+ - `skillwiki ingest` returns nonzero; retain any raw-only result for retry.
54
52
  - sha256 already exists in vault for the same source.
55
53
  ## Forbidden
56
54
  - Skipping `fetch-guard`.
57
- - Updating `index.md` or `log.md` before all pages validate.
55
+ - Creating a final typed page or editing `index.md`/`log.md` directly.
58
56
  - Modifying any existing file in `raw/`.
59
57
  - Writing raw ephemeral data directly to cloud-mounted wiki paths (`~/wiki/`).
60
58
  - Writing host-local absolute paths as canonical durable source references (see `using-skillwiki` → Portable Source References).
61
59
  - Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.
62
60
  ## Batch Mode
63
61
  When the user provides multiple sources (a directory of files, a list of URLs, or a multi-document input):
64
- 1. **Loop per source.** Execute steps 1–7 for each source individually (guard → fetch → identity guard → sensitive content guard → hash → generate → validate).
65
- 2. **Accumulate, don't write yet.** Collect all raw files and pages in memory. Do not write `index.md` or `log.md` until every source has validated.
66
- 3. **Fail fast.** If any page fails validation, STOP. Report all failures. Do not write index/log for any source.
67
- 4. **Deduplication.** Before writing each raw file, check `sha256` against existing vault raw sources. Skip sources whose content is already present.
68
- 5. **Single index/log update.** After all sources validate, write all raw files and pages, then update `index.md` and `log.md` once.
69
- 6. **Progress.** After each source completes validation, report progress (e.g., "Validated 3/10 sources").
62
+ 1. **Loop per source.** Execute steps 1–8 for each source individually, using one `skillwiki ingest` command per source.
63
+ 2. **Fail fast.** If an ingest command returns nonzero, STOP and report the retained raw-only state, if any, with its exact retry inputs.
64
+ 3. **Deduplication.** Let `skillwiki ingest` preserve immutable raw capture and skip sources whose content is already present.
65
+ 4. **Progress.** After each source completes, report the raw path, typed path or recovery state, and publisher operation ID.
package/skills/skills/wiki-query/SKILL.md CHANGED
@@ -23,7 +23,15 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
23
23
  5. **Read top candidates** in full (frontmatter + body).
24
24
  6. **Synthesize answer** with explicit citations to the candidate pages.
25
25
  7. **Sensitive content guard.** Before filing any query or comparison page, scan the generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact before writing. If the answer depends on preserving a live secret, STOP and ask for a redacted source or explicit rotation/remediation direction.
26
- 8. **Optional file.** If user accepts: write to `queries/<slug>.md` or `comparisons/<slug>.md` with full frontmatter, validate, then update `index.md` then `log.md`. If the filed page is a research/evaluation answer, recommendation, or comparison, end it with:
26
+ 8. **Optional file.** If the user accepts, first run `skillwiki page publish --help`. If it is unavailable, fail closed and leave the result unpublished. Otherwise:
27
+ 1. Resolve the vault and create a temporary directory outside the vault.
28
+ 2. Write the complete query/comparison page to `<temp>/page.md`, including final frontmatter, citations, Sources footer, and Decision Closeout.
29
+ 3. Run `skillwiki page publish <temp>/page.md <vault> --target queries/<slug>.md` (or `comparisons/<slug>.md`) and inspect the dry-run.
30
+ 4. Run the identical command with `--write` only when dry-run succeeds.
31
+ 5. On any nonzero result, retain the draft path and STOP; do not edit the final target, index.md, or log.md directly.
32
+ 6. Remove the temporary directory only after the publisher returns complete success.
33
+
34
+ If the filed page is a research/evaluation answer, recommendation, or comparison, end it with:
27
35
  ```markdown
28
36
  ## Decision Closeout
29
37
 
@@ -41,6 +49,7 @@ Use exactly one disposition. This is a prompt convention only; do not add CLI en
41
49
  When a wiki page (especially a work item `tasks.md`) claims that fixes were applied, features were completed, or files were removed — **verify on disk before accepting the claim**. In one incident, a `tasks.md` marked 6 items DONE but 5 were not actually applied: a script claimed "removed" was still 2020 bytes on disk, a crontab claimed "updated to 30min" was still `*/10`, and a build target claimed "verified has consumers" had no web server serving it.
42
50
  **Rule**: After reading a work item that declares completion, run at least one verification command per critical claim (check file existence, grep a config, inspect a crontab). Documents can drift from reality — the filesystem is the source of truth.
43
51
  ## Forbidden
44
- - Filing without `validate` passing.
52
+ - Filing without the `skillwiki page publish` dry-run passing.
53
+ - Directly creating a final typed page or separately editing `index.md` or `log.md` for its publication.
45
54
  - Skipping the orientation reads even for "quick" queries.
46
55
  - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault.
package/skills/using-skillwiki/SKILL.md CHANGED
@@ -59,6 +59,21 @@ sha256: # computed by skillwiki hash over body bytes after closing ---
59
59
  ## Sensitive Content Policy
60
60
  Vault content must not contain live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets. This includes development-only and local-only credentials. Redact values before filing using `[REDACTED:<kind>]` or `[REDACTED:<kind>:<fingerprint>]`. If a source contains live secrets, stop and ask for a redacted source or explicit rotation/remediation direction; do not preserve the secret in `raw/`.
61
61
 
62
+ ## Typed-Page Publication Contract
63
+
64
+ All new or updated typed-knowledge and meta pages MUST be published through
65
+ `skillwiki page publish`. Compose the complete page at an unpublished temporary
66
+ path, run publisher dry-run, then run the same command with `--write`.
67
+
68
+ - Do not directly create or edit the final typed-page path.
69
+ - Do not directly update `index.md` or append the page's structural log entry.
70
+ - If `skillwiki page publish --help` is unavailable, fail closed and leave the
71
+ result unpublished; update the active SkillWiki CLI/plugin channel first.
72
+ - `skillwiki validate --apply` is a legacy repair/compatibility path, not the
73
+ new-page publication path.
74
+ - Non-typed project work items and immutable raw sources keep their existing
75
+ workflows.
76
+
62
77
  ## Portable Source References
63
78
  The vault is shared across hosts, so host-local absolute paths are not durable source identity.
64
79
 
@@ -120,7 +135,7 @@ Use `prd_layer` + `prd_pipeline` from `.claude/dev-loop.config.md` as source of
120
135
 
121
136
  ## CLI Backbone
122
137
  All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, health reporting, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
123
- Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `fleet context`, `fleet validate`, `graph build`, `archive`, `drift`, `compound`, `tag-sync`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.
138
+ Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `fleet context`, `fleet validate`, `graph build`, `archive`, `drift`, `compound`, `tag-sync`, `tag reconcile`, `page publish`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.
124
139
  Run `skillwiki health <vault> --out /tmp/skillwiki-health.json --no-fail` for a bounded whole-system report that includes doctor, lint, vault-sync, query-readiness, source-freshness, risk flags, and self-check coverage. Run `skillwiki lint <vault> --summary` for lint-only bucket counts with capped examples and details commands. Run `skillwiki doctor` to diagnose setup/runtime issues only. Run `skillwiki config list` to see current configuration.
125
140
 
126
141
  ## Runtime Host Context and Fleet Freshness
package/skills/wiki-ingest/SKILL.md CHANGED
@@ -14,29 +14,26 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
14
14
  2. `index.md`
15
15
  3. Last 20–30 entries of `log.md`
16
16
  4. (Project context only) `projects/{slug}/README.md` and last ~5 work-item logs.
17
- ## Steps (in order — N6, N7, N8)
17
+ ## Steps (in order — deterministic raw capture and shared publication)
18
18
  0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`. Use the resolved vault path for all writes; use the canonical language for all generated prose.
19
19
  1. **Guard.** For each URL: run `skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
20
20
  2. **Fetch.** Use `web_fetch` (or read local file) under Layer 2 controls (the CLI Layer 2 fetcher applies in tests; in skill runtime use `web_fetch` directly and treat any error as STOP).
21
21
  - **Portable local-source rule:** follow `using-skillwiki` → Portable Source References. Do not use `source_url: file:///...` as the canonical durable reference; prefer commit-pinned GitHub `blob/<commit>/<path>` when resolvable, else empty `source_url` plus portable repo-relative prose.
22
- 3. **Identity guard.** Before writing raw files, ensure the target raw filename/title, `source_url`, fetched H1/title, and early body subject agree. If `skillwiki ingest` reports `INGEST_VALIDATION_FAILED` with `source identity conflict`, STOP. Do not fix by renaming after the fact; choose the correct title/source pair or ask the user.
23
- 4. **Sensitive content guard.** Before writing or filing any vault page, scan the source and generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact generated prose before writing. If the source itself must remain raw and contains a live secret, STOP instead of preserving it.
24
- 5. **Hash.** Write the raw file (frontmatter + body). Run `skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
25
- 6. **Generate page(s).** Compose typed-knowledge page(s) with citations pre-attached (`^[raw/...]` markers). Every page MUST include:
26
- - `> **TL;DR:**` blockquote as the first content after the title heading — a one-sentence summary of the page's key takeaway (under 200 chars). See SCHEMA.md `## TL;DR Convention`.
27
- - For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
28
- For generated `comparisons/` pages or evaluation-style `queries/` pages, end the body with:
29
- ```markdown
30
- ## Decision Closeout
31
-
32
- Disposition: no-op | concept | ADR | work-item | evidence-needed
33
- Reason: ...
34
- Follow-up: ...
35
- ```
36
- Use exactly one disposition. Keep this as a prompt convention, not a validator rule.
37
- 7. **Validate.** For each generated page: run `skillwiki validate <page>`. If exit ≠ 0, STOP — do not write index/log.
38
- 8. **Apply writes in order.** raw → page(s) → `index.md` → `log.md`.
39
- 9. **Confidence flag.** If only one source is cited, set `confidence: low`.
22
+ 3. **Stage pasted text as a file source.** `skillwiki ingest` accepts a readable local source file or HTTP(S) URL; it does **not** accept literal pasted text. For a paste, stage the exact text in a temporary file outside the vault, then pass its path to the normal command:
23
+ ```bash
24
+ skillwiki ingest <staged-paste-path> \
25
+ --vault <resolved-vault> \
26
+ --type <entity|concept|comparison|query> \
27
+ --title "<title>" \
28
+ --tags "<tag1,tag2>" \
29
+ --provenance <research|project>
30
+ ```
31
+ Record the staged path and exact command inputs before execution. If ingestion or typed-page publication fails, retain the staged source and exact command inputs for retry. Remove the staged file only after `skillwiki ingest` exits 0 after typed-page publication; confirm the non-dry-run result reports its raw path, typed path, and publisher operation. Do not stage pasted text inside the vault.
32
+ 4. **Identity guard.** Before writing raw files, ensure the target raw filename/title, `source_url`, fetched H1/title, and early body subject agree. If `skillwiki ingest` reports `INGEST_VALIDATION_FAILED` with `source identity conflict`, STOP. Do not fix by renaming after the fact; choose the correct title/source pair or ask the user.
33
+ 5. **Sensitive content guard.** Before writing or filing any vault page, scan the source and generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact generated prose before writing. If the source itself must remain raw and contains a live secret, STOP instead of preserving it.
34
+ 6. **Feature-detect publication.** Run `skillwiki page publish --help`. If unavailable, fail closed and leave typed output unpublished; update the active SkillWiki CLI/plugin channel first.
35
+ 7. **Ingest and publish.** Use `skillwiki ingest` for deterministic source capture and typed-page publication. The command writes an immutable raw source first and delegates the typed page, taxonomy, index, and structural log entry to the shared page publisher. Supply the resolved vault, type, title, tags, and provenance through the command options.
36
+ 8. **Recovery.** Never create the final typed page or edit index.md/log.md directly. A raw-only result after publication failure is valid recovery state. Keep the exact command inputs and retry; do not delete or overwrite the raw source.
40
37
  ## Provenance defaults
41
38
  - Default `provenance: research`.
42
39
  - If cwd is inside `projects/{slug}/`, set `provenance: project` and add `provenance_projects: ["[[slug]]"]`.
@@ -50,20 +47,19 @@ Raw ephemeral data (market feeds, logs, transient JSON) must be written to the *
50
47
  - Fetch timeout / size limit exceeded.
51
48
  - `INGEST_VALIDATION_FAILED` with `source identity conflict`.
52
49
  - Source or generated content contains unredacted live credentials or other authenticating secrets.
53
- - `validate` non-zero on any page.
50
+ - `skillwiki page publish --help` is unavailable.
51
+ - `skillwiki ingest` returns nonzero; retain any raw-only result for retry.
54
52
  - sha256 already exists in vault for the same source.
55
53
  ## Forbidden
56
54
  - Skipping `fetch-guard`.
57
- - Updating `index.md` or `log.md` before all pages validate.
55
+ - Creating a final typed page or editing `index.md`/`log.md` directly.
58
56
  - Modifying any existing file in `raw/`.
59
57
  - Writing raw ephemeral data directly to cloud-mounted wiki paths (`~/wiki/`).
60
58
  - Writing host-local absolute paths as canonical durable source references (see `using-skillwiki` → Portable Source References).
61
59
  - Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.
62
60
  ## Batch Mode
63
61
  When the user provides multiple sources (a directory of files, a list of URLs, or a multi-document input):
64
- 1. **Loop per source.** Execute steps 1–7 for each source individually (guard → fetch → identity guard → sensitive content guard → hash → generate → validate).
65
- 2. **Accumulate, don't write yet.** Collect all raw files and pages in memory. Do not write `index.md` or `log.md` until every source has validated.
66
- 3. **Fail fast.** If any page fails validation, STOP. Report all failures. Do not write index/log for any source.
67
- 4. **Deduplication.** Before writing each raw file, check `sha256` against existing vault raw sources. Skip sources whose content is already present.
68
- 5. **Single index/log update.** After all sources validate, write all raw files and pages, then update `index.md` and `log.md` once.
69
- 6. **Progress.** After each source completes validation, report progress (e.g., "Validated 3/10 sources").
62
+ 1. **Loop per source.** Execute steps 1–8 for each source individually, using one `skillwiki ingest` command per source.
63
+ 2. **Fail fast.** If an ingest command returns nonzero, STOP and report the retained raw-only state, if any, with its exact retry inputs.
64
+ 3. **Deduplication.** Let `skillwiki ingest` preserve immutable raw capture and skip sources whose content is already present.
65
+ 4. **Progress.** After each source completes, report the raw path, typed path or recovery state, and publisher operation ID.
package/skills/wiki-query/SKILL.md CHANGED
@@ -23,7 +23,15 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
23
23
  5. **Read top candidates** in full (frontmatter + body).
24
24
  6. **Synthesize answer** with explicit citations to the candidate pages.
25
25
  7. **Sensitive content guard.** Before filing any query or comparison page, scan the generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact before writing. If the answer depends on preserving a live secret, STOP and ask for a redacted source or explicit rotation/remediation direction.
26
- 8. **Optional file.** If user accepts: write to `queries/<slug>.md` or `comparisons/<slug>.md` with full frontmatter, validate, then update `index.md` then `log.md`. If the filed page is a research/evaluation answer, recommendation, or comparison, end it with:
26
+ 8. **Optional file.** If the user accepts, first run `skillwiki page publish --help`. If it is unavailable, fail closed and leave the result unpublished. Otherwise:
27
+ 1. Resolve the vault and create a temporary directory outside the vault.
28
+ 2. Write the complete query/comparison page to `<temp>/page.md`, including final frontmatter, citations, Sources footer, and Decision Closeout.
29
+ 3. Run `skillwiki page publish <temp>/page.md <vault> --target queries/<slug>.md` (or `comparisons/<slug>.md`) and inspect the dry-run.
30
+ 4. Run the identical command with `--write` only when dry-run succeeds.
31
+ 5. On any nonzero result, retain the draft path and STOP; do not edit the final target, index.md, or log.md directly.
32
+ 6. Remove the temporary directory only after the publisher returns complete success.
33
+
34
+ If the filed page is a research/evaluation answer, recommendation, or comparison, end it with:
27
35
  ```markdown
28
36
  ## Decision Closeout
29
37
 
@@ -41,6 +49,7 @@ Use exactly one disposition. This is a prompt convention only; do not add CLI en
41
49
  When a wiki page (especially a work item `tasks.md`) claims that fixes were applied, features were completed, or files were removed — **verify on disk before accepting the claim**. In one incident, a `tasks.md` marked 6 items DONE but 5 were not actually applied: a script claimed "removed" was still 2020 bytes on disk, a crontab claimed "updated to 30min" was still `*/10`, and a build target claimed "verified has consumers" had no web server serving it.
42
50
  **Rule**: After reading a work item that declares completion, run at least one verification command per critical claim (check file existence, grep a config, inspect a crontab). Documents can drift from reality — the filesystem is the source of truth.
43
51
  ## Forbidden
44
- - Filing without `validate` passing.
52
+ - Filing without the `skillwiki page publish` dry-run passing.
53
+ - Directly creating a final typed page or separately editing `index.md` or `log.md` for its publication.
45
54
  - Skipping the orientation reads even for "quick" queries.
46
55
  - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault.