@kernaut/kernaut-resources 0.1.17-beta.1 → 0.1.18

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/docs/history/mcp/fut-1-validation-checklist.md

@@ -1,228 +0,0 @@
-# KernelWiki MCP Server — Agent Validation Checklist
-
-This checklist is a handoff artifact for FUT-1 (live end-to-end agent validation). It documents what to verify when testing the MCP server with real agents.
-
-## Pre-requisites
-
-- [ ] Python 3.9+ installed
-- [ ] PyYAML installed (`pip install pyyaml`)
-- [ ] Wiki root accessible (contains `data/tags.yaml` and `wiki/`)
-- [ ] stdio smoke tests pass: `bash scripts/test_mcp_smoke.sh`
-- [ ] HTTP smoke tests pass: `bash scripts/test_mcp_http_smoke.sh`
-
-## Registration Commands
-
-### Claude Code
-
-```bash
-claude mcp add kernelwiki -- python3 scripts/mcp_server.py
-```
-
-### Codex CLI
-
-```bash
-codex mcp add kernelwiki -- python3 scripts/mcp_server.py
-```
-
-### Codex CLI remote HTTP
-
-Start the remote server:
-
-```bash
-BLACKWELL_WIKI_ROOT="$PWD" MCP_LOG_FILE=/tmp/kernelwiki-mcp.log \
-  python3 scripts/mcp_http_server.py --host 0.0.0.0 --port 8765
-```
-
-Register from another machine:
-
-```bash
-codex mcp add kernelwiki-remote --url http://SERVER_HOST:8765/mcp
-```
-
-With bearer-token auth:
-
-```bash
-export KERNELWIKI_MCP_TOKEN='replace-with-a-long-random-token'
-codex mcp add kernelwiki-remote \
-  --url http://SERVER_HOST:8765/mcp \
-  --bearer-token-env-var KERNELWIKI_MCP_TOKEN
-```
-
-With dynamic SQLite token CRUD:
-
-```bash
-python3 scripts/mcp_token_admin.py --db data/mcp_tokens.sqlite3 add laptop
-MCP_TOKEN_DB=data/mcp_tokens.sqlite3 MCP_ADMIN_TOKEN='admin-secret' \
-  python3 scripts/mcp_http_server.py --host 0.0.0.0 --port 8765
-```
-
-### Claude Desktop
-
-Add to `claude_desktop_config.json` (see `docs/mcp-client-config.md` for full snippet).
-
-## Expected tools/list Output
-
-```bash
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python3 scripts/mcp_server.py 2>/dev/null
-```
-
-HTTP equivalent:
-
-```bash
-curl -sS http://127.0.0.1:8765/mcp \
-  -H 'Content-Type: application/json' \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
-```
-
-Expected response (abbreviated):
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "result": {
-    "tools": [
-      {"name": "wiki_query", "description": "Search the KernelWiki knowledge base by keywords and filters. Returns ranked pages with titles, types, and key metadata.", "inputSchema": {"type": "object", "properties": {"query": {"type": "array", "items": {"type": "string"}, "description": "Free-text keyword list"}, "..."  : "..."}, "required": []}},
-      {"name": "wiki_get_page", "description": "Retrieve a wiki page by its id or relative path. Returns full content, frontmatter, and optionally artifact code files.", "inputSchema": {"type": "object", "properties": {"lookup": {"type": "string", "description": "Page id (e.g. kernel-flash-attention-4) or relative path"}, "..." : "..."}, "required": ["lookup"]}},
-      {"name": "wiki_grep", "description": "Regex text search across wiki markdown files and optionally source code artifacts. Returns matching lines with context.", "inputSchema": {"type": "object", "properties": {"patterns": {"type": "array", "items": {"type": "string"}, "description": "Regex pattern(s) — all must match unless any_match is true"}, "..." : "..."}, "required": ["patterns"]}}
-    ]
-  }
-}
-```
-
-## Sample tools/call Invocation and Response
-
-### Query
-
-```bash
-echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"wiki_query","arguments":{"query":["tcgen05"],"vendor":"nvidia","limit":3,"compact":true}}}' | python3 scripts/mcp_server.py 2>/dev/null
-```
-
-Expected response shape:
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 2,
-  "result": {
-    "content": [{"type": "text", "text": "{\"ok\":true,\"total_hits\":N,\"returned\":3,\"truncated\":true,\"data\":[...]}"}],
-    "isError": false
-  }
-}
-```
-
-### Page retrieval
-
-```bash
-echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"wiki_get_page","arguments":{"lookup":"hw-tcgen05-mma","body_only":true}}}' | python3 scripts/mcp_server.py 2>/dev/null
-```
-
-### Not-found error
-
-```bash
-echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"wiki_get_page","arguments":{"lookup":"nonexistent"}}}' | python3 scripts/mcp_server.py 2>/dev/null
-```
-
-Expected: `{"ok":false,"error_code":"PAGE_NOT_FOUND","message":"No page found for 'nonexistent'"}`
-
-## Claude Code Validation
-
-1. **Setup**: `claude mcp add kernelwiki -- python3 scripts/mcp_server.py`
-2. **Tool discovery**: Run `claude mcp list` — confirm `kernelwiki` appears with 3 tools
-3. **Query**: Ask Claude to "search KernelWiki for tcgen05 techniques" — verify it calls `wiki_query`
-4. **Page retrieval**: Ask "show me the page for hw-tcgen05-mma" — verify `wiki_get_page` call
-5. **Grep**: Ask "find all mentions of tcgen05.fence in the wiki" — verify `wiki_grep` call
-6. **Error handling**: Ask for a nonexistent page — verify `PAGE_NOT_FOUND` error response
-7. **Artifact loading**: Ask to "show code for [page-with-artifacts]" with `include_code: true`
-
-## Codex CLI Validation
-
-1. **Setup**: `codex mcp add kernelwiki -- python3 scripts/mcp_server.py`
-2. **Tool listing**: Verify tools are discovered
-3. **Query**: Request a keyword search — verify structured response
-4. **Page retrieval**: Request a specific page — verify content returned
-5. **Grep**: Request a regex search — verify matches returned
-
-## Remote HTTP Validation
-
-1. **Start**: `python3 scripts/mcp_http_server.py --host 0.0.0.0 --port 8765`
-2. **Health**: `curl -fsS http://SERVER_HOST:8765/healthz`
-3. **Tool discovery**: POST `tools/list` to `http://SERVER_HOST:8765/mcp`
-4. **Client registration**: `codex mcp add kernelwiki-remote --url http://SERVER_HOST:8765/mcp`
-5. **Auth path**: If `MCP_AUTH_TOKEN` is set, verify missing `Authorization` returns HTTP 401 and `Authorization: Bearer <token>` succeeds
-6. **Network path**: From a second machine, repeat health and `tools/list`
-
-## Dynamic Token CRUD Validation
-
-1. **Create DB token**: `python3 scripts/mcp_token_admin.py --db /tmp/kw-tokens.sqlite add laptop`
-2. **Start with DB**: `MCP_TOKEN_DB=/tmp/kw-tokens.sqlite MCP_ADMIN_TOKEN=admin python3 scripts/mcp_http_server.py --host 0.0.0.0 --port 8765`
-3. **Read/list**: `python3 scripts/mcp_token_admin.py --db /tmp/kw-tokens.sqlite list` and `GET /admin/tokens` with admin bearer
-4. **Auth works**: Call `POST /mcp` with the created token and verify success
-5. **Update/disable**: Disable the token by CLI or `PATCH /admin/tokens/{id}` and verify the same token returns HTTP 401 without restarting the server
-6. **Enable**: Re-enable and verify the same token succeeds
-7. **Rotate**: Rotate the token, verify old token fails and new token succeeds
-8. **Create new live token**: Add another token while the server is running and verify it succeeds immediately
-9. **Delete**: Delete a token and verify it fails immediately
-10. **No secret leakage**: Confirm list/get responses do not include plaintext token values; only add/rotate responses do
-
-## Claude Desktop Validation
-
-1. **Setup**: Add config to `claude_desktop_config.json` per docs
-2. **Tool visibility**: Confirm tools appear in Claude's tool list
-3. **Basic query**: Run a search query through the chat interface
-
-## Protocol Compliance
-
-- [ ] Initialize handshake completes (protocolVersion: 2024-11-05)
-- [ ] notifications/initialized accepted without response
-- [ ] tools/list returns 3 tool definitions with valid inputSchema
-- [ ] tools/call returns `{content: [{type: "text", text: "<JSON>"}], isError: bool}`
-- [ ] Unknown methods return JSON-RPC error -32601
-- [ ] Malformed JSON returns parse error -32700
-- [ ] Non-object request returns invalid request -32600
-- [ ] ping returns empty result `{}`
-- [ ] HTTP `POST /mcp` accepts single JSON-RPC requests and batches
-- [ ] HTTP `GET /healthz` returns server and wiki root metadata
-- [ ] HTTP bearer-token mode rejects unauthenticated requests with 401
-- [ ] SQLite token DB mode validates tokens dynamically without restart
-- [ ] Token CLI supports create/list/get/update/enable/disable/rotate/delete
-- [ ] HTTP admin API supports create/list/get/update/rotate/delete when `MCP_ADMIN_TOKEN` is set
-- [ ] Plaintext token values are stored hashed and only printed on create/rotate
-
-## Security
-
-- [ ] Path traversal (`../../etc/passwd`) returns `PATH_OUTSIDE_ROOT` error
-- [ ] Null bytes in lookup are rejected with `INVALID_PARAMS`
-- [ ] Stderr is never written to stdout (protocol integrity)
-- [ ] Large responses are truncated to 500 KiB budget
-- [ ] Artifact file symlinks that escape WIKI_ROOT are silently skipped
-
-## Domain Error Codes
-
-- [ ] `PATH_OUTSIDE_ROOT`: lookup path escapes wiki root
-- [ ] `REGEX_ERROR`: invalid regex pattern in grep
-- [ ] `PAGE_NOT_FOUND`: no page matches lookup
-- [ ] `INVALID_PARAMS`: missing/invalid parameter, unknown tool, bad enum value
-- [ ] `INTERNAL_ERROR`: unexpected server exception
-
-## Edge Cases
-
-- [ ] Empty query returns all pages (sorted by path)
-- [ ] Invalid regex in grep returns `REGEX_ERROR` with description
-- [ ] Unknown tool name returns `INVALID_PARAMS`
-- [ ] Parameters exceeding limits are clamped (e.g., limit > 200 → 200)
-- [ ] Missing required parameters return `INVALID_PARAMS`
-- [ ] Boolean/string values for integer params return `INVALID_PARAMS`
-- [ ] `hw-tcgen05` resolves to `hw-tcgen05-mma` via prefix matching
-- [ ] Server stays alive after errors (verified by multi-request session in smoke tests)
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| No response from server | Stderr corruption, bad import | Set `MCP_LOG_FILE=/tmp/mcp.log` and check logs |
-| `BLACKWELL_WIKI_ROOT` error | Wiki root not found | Set env var or run from repo root |
-| Tools not listed in agent | Server name mismatch | Use `kernelwiki` as the server name |
-| `PATH_OUTSIDE_ROOT` | Lookup contains `..` or resolves outside root | Use page IDs instead of paths |
-| Truncated response | Output exceeds 500 KiB | Reduce `limit` or use `compact` mode |
-| `REGEX_ERROR` | Invalid regex syntax | Escape special chars: `[](){}.*+?^$|\` |

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/docs/history/planning/2026-06-02-reference-audit/findings.md

@@ -1,16 +0,0 @@
-# Findings: KernelWiki reference audit
-
-
-## Baseline audit results
-- `python3 scripts/validate.py` passes: 2490 files, 2265 source IDs, 117 bundles, 0 errors.
-- Custom path scan found 152 `sources/experience/.../artifacts` references, 184 frontmatter `artifacts:` path issues, and 27 frontmatter `source[].path` issues.
-- The validator currently misses these because legacy `source:` and `artifacts:` fields are not schema-validated as local paths.
-- Detailed report written to `docs/source-artifact-reference-audit.md`.
-
-## Post-fix verification
-- `python3 scripts/validate.py` passes after path rewrites and validator guardrail changes.
-- Custom audit excluding historical prose reports:
-  - source-artifact-mix: 0
-  - frontmatter source[].path issues: 0
-  - active frontmatter artifacts path issues: 0
-- Remaining old kp-mvp and absolute path findings are mostly historical docs/templates/verbatim upstream PR text, not active source/artifact frontmatter.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/docs/history/planning/2026-06-02-reference-audit/progress.md

@@ -1,8 +0,0 @@
-# Progress
-
-- Initialized reference audit plan.
-- Ran custom path audit and generated consolidated report at docs/source-artifact-reference-audit.md.
-- Applied source/artifact path fixes across active wiki/source/task pages.
-- Added validate.py guardrails for legacy source/artifacts path fields.
-- Re-ran validate.py successfully after fixes.
-- Re-ran custom audit: source-artifact-mix=0, frontmatter source issues=0, active artifact field issues=0.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/docs/history/planning/2026-06-02-reference-audit/task_plan.md

@@ -1,19 +0,0 @@
-# Task Plan: KernelWiki source/artifact reference audit
-
-## Goal
-全方位排查 KernelWiki 中 source 与 artifact 分离不彻底导致的引用问题：不存在路径、旧 kp-mvp `80-experience/.../artifacts` 路径、绝对路径、source_refs/artifact_dir 不一致、wiki body 中 `source` 标题下误放 artifact 路径等。
-
-## Phases
-- [complete] Phase 1: Baseline inventory and identify relevant schema/path conventions.
-- [complete] Phase 2: Scan all Markdown/YAML files for path-like references and classify external corpus vs local artifact vs missing.
-- [complete] Phase 3: Specifically audit `sources/experience`, `artifacts/experience`, and `wiki/nvidia/**` migrated pages.
-- [complete] Phase 4: Produce consolidated findings and recommended fixes.
-
-## Decisions
-- Do not perform bulk migration fixes unless explicitly requested; this turn focuses on audit/reporting.
-- Treat files under `artifacts/experience/**` as artifact bundles, not source corpus paths.
-- Treat external repo references as valid only when represented as logical corpus source (`source_id + repo-relative path`) or resolvable via corpus localize/manifest.
-
-## Errors Encountered
-| Error | Attempt | Resolution |
-|---|---|---|

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/docs/history/planning/2026-06-10-library-call-isolation/active-plan.txt

@@ -1 +0,0 @@
-2026-06-10-library-call-isolation

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/docs/history/planning/2026-06-10-library-call-isolation/findings.md

@@ -1,24 +0,0 @@
-# Findings: Library-call content isolation
-
-## Open Questions / To Resolve
-- Which directories and Markdown files are included by the query/index pipeline?
-- What exact patterns in this knowledge base represent “库调用”?
-- Which exclusion mechanism prevents content from being retrieved by `query`?
-
-## Repository/query indexing rules
-- `scripts/query.py::load_all_pages()` loads Markdown only from top-level `sources/` and `wiki/`.
-- `scripts/generate-indices.py::collect_all_pages()` also loads Markdown only from `sources/` and `wiki/` and writes derived indices under `queries/`.
-- `scripts/grep_wiki.py` default scopes are `wiki` and `sources`; `nonquery/` is not searched by default.
-- Therefore a top-level `nonquery/library-calls/` archive is outside the normal queryable corpus.
-
-## Library-call inventory and handling
-- Moved all eight `wiki/nvidia/operator-routing/*/library-fallback.md` pages into `nonquery/library-calls/operator-routing/<op>/library-fallback.md`.
-- Archived additional removed/generalized wiki snippets in `nonquery/library-calls/extracted-wiki-snippets.md`.
-- Archived exact source snippets containing high-level library-call tokens in `nonquery/library-calls/extracted-source-snippets.md` before generalizing them in queryable `sources/` pages.
-- Rewrote operator-routing INDEX/TASK-PACKET/ROUTING pages to be custom-kernel focused and removed links/IDs/titles for moved fallback pages.
-
-## Verification evidence
-- `python3 scripts/generate-indices.py` now reports `Collected 2482 pages from sources/ and wiki/`; the moved `nonquery/` archive is not included.
-- `python3 scripts/validate.py` passes: 2482 files, 2265 source IDs, 117 asset bundles, 6 candidate ledgers, 0 errors.
-- Strict scan over queryable roots found no exact high-level library-call tokens matching: `torch.*`, `thrust::...`, `cub::Device...`, `cublas...`, `CUBLAS_...`, `cudnn...`, `cuDNN`, `flashinfer.<module>.<api>`, or `library-fallback`.
-- Exact `scripts/query.py --paths-only` checks return no paths for: `library-fallback`, `routing-elementwise-library-fallback`, `torch.sum`, `torch.compile`, `thrust::transform`, `cub::DeviceReduce::Sum`, `cublasGemmEx`, `cublasLtMatrixTransform`, `cudnnPoolingForward`, and `flashinfer.fused_moe.trtllm_fp8_block_scale_moe`.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/docs/history/planning/2026-06-10-library-call-isolation/progress.md

@@ -1,9 +0,0 @@
-# Progress
-
-- Initialized dedicated planning files for library-call content isolation.
-- Mapped query/index scopes: `sources/` + `wiki/` only; selected top-level `nonquery/library-calls/` as archive outside retrieval.
-- Moved all operator-routing `library-fallback.md` pages out of `wiki/` into `nonquery/library-calls/operator-routing/`.
-- Rewrote affected operator routing, foundations, kernel, source, and generated query-index Markdown to remove exact high-level library-call tokens from queryable roots.
-- Archived original removed/generalized snippets under `nonquery/library-calls/extracted-wiki-snippets.md` and `nonquery/library-calls/extracted-source-snippets.md`.
-- Regenerated query indices and updated README/SKILL page counts to 2482.
-- Verification passed: strict exact-token grep over `sources wiki queries`, exact `query.py --paths-only` checks for moved/API terms, and `python3 scripts/validate.py`.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/docs/history/planning/2026-06-10-library-call-isolation/task_plan.md

@@ -1,27 +0,0 @@
-# Task Plan: Isolate library-call content from queryable knowledge files
-
-## Goal
-找到当前知识库中所有包含“库调用”的 Markdown 知识文件，修改相关知识文件，将库调用相关内容全部挪到单独文件夹，并确保这些库调用内容不会被 query 检索到。
-
-## Requirements / Success Criteria
-- [x] Inventory all queryable Markdown knowledge files and identify the query/indexing inclusion/exclusion rules.
-- [x] Detect Markdown knowledge files that contain library-call content (imports/includes, framework/library API calls, third-party helper usage, or code/prose focused on invoking libraries rather than kernel implementation concepts).
-- [x] Move the library-call-related content into a dedicated isolation folder outside the queryable knowledge corpus.
-- [x] Rewrite the original knowledge Markdown files so queryable content no longer includes those library-call sections or references that would surface the isolated content.
-- [x] Verify with repository search and the query/index pipeline that isolated library-call content is excluded from query retrieval.
-
-## Phases
-- [complete] Phase 1: Restore context and map repository/query indexing rules.
-- [complete] Phase 2: Scan Markdown knowledge files for library-call content and build an evidence inventory.
-- [complete] Phase 3: Create/choose the isolation folder and move extracted library-call content there.
-- [complete] Phase 4: Rewrite affected Markdown knowledge files to remove/move library-call content.
-- [complete] Phase 5: Verify by text scans, validation scripts, and query/index checks.
-
-## Decisions
-- Treat repository files and command output as authoritative.
-- Preserve original knowledge where possible by moving rather than deleting library-call content.
-- The isolation folder must be excluded from the query corpus/index, not merely hidden by naming.
-
-## Errors Encountered
-| Error | Attempt | Resolution |
-|---|---|---|