c64-kb 0.17.0

package/dist/server/tools-briefings.js

@@ -0,0 +1,70 @@
+/** The two briefing tools that plan a whole program in one call. */
+import { z } from "zod";
+import { demoBriefing, gameBriefing } from "../tools/briefings.js";
+import { BriefingSchema } from "../schemas/tool-outputs.js";
+import { defineTool, READ_ONLY } from "./define-tool.js";
+export const demoBriefingTool = defineTool({
+    name: "c64_demo_briefing",
+    title: "Plan a C64 demo",
+    description: `**Phase 5 anchor tool.** Generate a complete, structured C64 demo plan from a natural-language brief in a single call. Internally orchestrates: vector search → technique lookup (graph enrichment per technique) → compatibility check (cross-technique conflict detection) → pitfall surfacing → toolchain split → build order with recipes.
+
+Purpose: Replaces the 9-tool manual composition that the c64_demo_brief Prompt requires from the agent. One call returns the full structured plan as typed JSON plus a human-readable markdown summary.
+
+Inputs: 'description' is a free-form demo brief (e.g. "sprite scroller with raster bars and SID music"). The tool extracts implied techniques via hybrid vector + keyword search, enriches each from the graph, and synthesises the plan. 'archetype' (optional) is the snake_case name of a demo form from docs/demo-design/intro-cracktro-patterns.md (cracktro, demo_intro, pack_intro, dentro, party_intro_4k); "Demo Intro" and "demo-intro" are read as demo_intro. Its technique fingerprint is forced into the proposal past the three-per-category cap and its common pitfalls are added to the pitfalls, exactly as c64_game_briefing does for a game archetype.
+
+Output: {brief, proposed_techniques[], compatibility{conflicts, warnings, shared_infrastructure}, pitfalls[], toolchain_split{primary, cycle_tight_handoff[], rationale}, build_order[{step, label, recipes[]}], budget{region, frame_cycles, cycles_per_frame_sum, cycles_low, fixed_loss_cycles, cycles_verdict, ram_budget_bytes, bytes_sum, bytes_verdict, contributors[{name, cycles_per_frame?, cycles_per_frame_typical?, bytes?, basis, measured_on?}], excluded[{name, reason, by?}], unknown[], to_measure[{technique, recipe}], without_cost[], weakest_basis, is_floor, assumptions[]}}. 'brief' is a one-sentence summary. 'proposed_techniques' carry register/KERNAL sets and implementing recipe names. 'toolchain_split.primary' is always "oscar64"; 'cycle_tight_handoff' names the raster/effect techniques handed to KickAssembler. 'budget' applies c64_plan_budget's rules to the proposed set, every technique in one play frame (PAL 19,656 cycles; NTSC 17,095; PAL unless every region-locked technique is NTSC): cycles_per_frame_sum is the high end (worst frames), cycles_low the low end (typical frames where a page states one), fixed_loss_cycles the badline and sprite DMA charge; excluded names members left out (multi_frame, included_by, inside_band_of, whole_program_bytes) and unknown the members with no cycles figure, each with a recipe to measure it on in to_measure. cycles_verdict is "over" when the work that runs every frame plus the loss no figure can hold passes the frame, "under" when nothing is unknown or multi-frame and the high end plus losses fit, "no_data" when nothing contributed, and "undetermined" otherwise (since tools 2.0.0; before, a missing figure counted as zero and the verdict said "under"). bytes_code + bytes_data are summed against a stated RAM budget of 38,911 bytes ($0801-$9FFF); bytes_verdict is "over", "under" or "no_data". 'without_cost' names the proposed techniques with no Cost line; when a cycles figure is unknown 'is_floor' is true and both sums are floors. 'weakest_basis' is the least trustworthy basis word among the contributors (measured-vice > derived-listing > arithmetic > estimated). With 'archetype' given, 'archetype' {name, title, kind, features[], risks[]} repeats what the graph holds, or 'archetype_not_found' {requested, known[]} lists every Archetype name the graph has (game and demo) when the name matches none; the plan is then built from the description alone and nothing is guessed.
+
+When to use: Start every new C64 demo design session with this tool. The structured output guides all follow-up tool calls (c64_technique_lookup, c64_check_compatibility, c64_pitfalls_for, c64_recipe_lookup) if deeper drill-down is needed.
+
+Examples: {"description": "sprite scroller with raster bars"} → plan with scroll + raster + stable_raster_irq techniques, compatibility check, pitfalls, build order. {"description": "FLI image viewer with music"} → bitmap + SID techniques, fli_image recipe in build order. {"description": "a small cracktro", "archetype": "cracktro"} → the cracktro page's fingerprint (stable raster, side border, sprite chain, scroller, raster bars, SID play) forced in, with its pitfalls.
+
+See also: c64_game_briefing for game-framed plans. c64_demo_brief Prompt as an alternate entry point (agent-composed, less structured).
+
+Limitations: Technique selection is heuristic (vector search + keyword overlap). For exotic briefs, the proposed set may miss niche techniques — follow up with c64_techniques_for to discover them. Compatibility check is structural (shared registers/KERNAL), not semantic.`,
+    inputSchema: {
+        description: z
+            .string()
+            .describe("Natural-language demo brief (e.g. 'sprite scroller with raster bars and SID music')"),
+        archetype: z
+            .string()
+            .optional()
+            .describe("Optional demo form: snake_case name of an Archetype node of kind demo from docs/demo-design/intro-cracktro-patterns.md (cracktro, demo_intro, pack_intro, dentro, party_intro_4k)"),
+    },
+    outputSchema: BriefingSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ description, archetype }) => demoBriefing(description, archetype),
+});
+export const gameBriefingTool = defineTool({
+    name: "c64_game_briefing",
+    title: "Plan a C64 game",
+    description: `**Phase 5 anchor tool.** Generate a complete, structured C64 game plan from a natural-language brief and an archetype name in a single call. Internally orchestrates: archetype lookup → vector search → technique lookup → compatibility check → pitfall surfacing → toolchain split → build order.
+
+Purpose: Replaces the 9-tool manual composition that the c64_game_brief Prompt requires from the agent. One call returns the full structured plan: proposed techniques for the game mechanic, register/KERNAL sets, pitfalls to avoid, Oscar64-primary + KickAssembler-for-hot-paths toolchain split, and a step-by-step build order.
+
+Inputs: 'description' is a free-form game brief (e.g. "vertical scrolling shoot-em-up with enemy sprites"). 'archetype' is the snake_case name of an Archetype node from docs/game-design/c64-game-archetypes.md (vertical_shmup, horizontal_shmup, single_screen_platformer, scrolling_platformer, top_down_adventure, puzzle, text_adventure, action_puzzle, sports, racing, beat_em_up); "Vertical Shmup" and "vertical-shmup" are read as vertical_shmup. Optional; without it the brief is routed to the game archetype whose **Brief words:** line it matches most (a road, a car or Spy Hunter reach vertical_shmup; pseudo-3D or racing reach racing), 'archetype.inferred_from' lists the words, and a tie or no match leaves the plan without an archetype. It is always a game plan (before 2026-09-23 a call without an archetype was framed as a demo).
+
+What the archetype does: its FEATURES edges (the page's technique fingerprint) are forced into proposed_techniques regardless of the keyword scorer and exempt from the per-category cap; its RISKS edges (the page's common pitfalls) are added to pitfalls[]; its title is appended to the search text. The page is the source of truth, not a table in this tool. Its GameDesigns (whole games INSTANCE_OF it, from docs/game-design/designs) are listed in 'designs[]' {name, title, realised_by[], composes[{technique, phase}], measured[{phase, region, worst, typical, basis, source}]}; pass a name to c64_plan_budget as 'design' to budget it by phase against its measured frame.
+
+Output: the briefing schema, including 'budget' (the plan added up from each technique's **Cost:** line: cycles_per_frame against the region's frame, bytes against a stated 38,911-byte RAM budget, 'without_cost' naming the techniques with no line so the sums read as floors, and 'weakest_basis'); 'archetype' {name, title, kind, features[], risks[], inferred_from?[]} repeating what the graph holds, or 'archetype_not_found' {requested, known[]} when the name matches no Archetype node, as for c64_demo_briefing, plus the game scaffold step when an archetype was named or routed. In the not-found case the plan is still built from the description alone; nothing is guessed. The build order's step 1 lists the recipes that SCAFFOLD the resolved archetype (Recipe -[:SCAFFOLDS]-> Archetype, authored by the recipe's scaffolds: key); the text names each recipe's page to copy. A graph with no Archetype nodes still offers oscar64-simple-shmup for a shmup key.
+
+When to use: Start every new C64 game design session with this tool. Read 'archetype_not_found.known' if the name you tried was not accepted.
+
+Examples: {"description": "vertical shoot-em-up", "archetype": "vertical_shmup"} → the ten fingerprint techniques (soft_scroll_v, scroll_panel_split, sprite_multiplex_game, per_frame_hitbox, wave_director, stable_raster_irq, double_irq, sid_voice_setup, sid_play_routine_pattern, sprite_collision_detect) plus the four named pitfalls, oscar64-simple-shmup in step 1. {"description": "Spy Hunter style road shooter"} → routed to vertical_shmup; the fingerprint plus vehicle_control, car_contact_response and lane_pursuit_ai from the brief's words. {"description": "a tetris clone", "archetype": "shmup"} → archetype_not_found with the known names.
+
+See also: c64_demo_briefing for demo (non-game) plans. c64_game_brief Prompt as an alternate entry point (agent-composed, less structured).
+
+Limitations: Technique discovery beyond the fingerprint is the same heuristic as c64_demo_briefing. A graph ingested before schema 21 has no Archetype nodes; the tool then falls back to a four-word keyword table and reports neither field.`,
+    inputSchema: {
+        description: z
+            .string()
+            .describe("Natural-language game brief (e.g. 'vertical scrolling shoot-em-up with enemy sprites')"),
+        archetype: z
+            .string()
+            .optional()
+            .describe("Archetype node name from docs/game-design/c64-game-archetypes.md: vertical_shmup | horizontal_shmup | single_screen_platformer | scrolling_platformer | top_down_adventure | puzzle | text_adventure | action_puzzle | sports | racing | beat_em_up"),
+    },
+    outputSchema: BriefingSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ description, archetype }) => gameBriefing(description, archetype),
+});
+//# sourceMappingURL=tools-briefings.js.map

package/dist/server/tools-briefings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-briefings.js","sourceRoot":"","sources":["../../src/server/tools-briefings.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC;IACzC,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,iBAAiB;IACxB,WAAW,EAAE;;;;;;;;;;;;;;gRAciQ;IAC9Q,WAAW,EAAE;QACX,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,CAAC,qFAAqF,CAAC;QAClG,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,mLAAmL,CACpL;KACJ;IACD,YAAY,EAAE,cAAc,CAAC,KAAK;IAClC,WAAW,EAAE,SAAS;IACtB,GAAG,EAAE,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC;CAC1E,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC;IACzC,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,iBAAiB;IACxB,WAAW,EAAE;;;;;;;;;;;;;;;;+OAgBgO;IAC7O,WAAW,EAAE;QACX,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,CAAC,wFAAwF,CAAC;QACrG,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,qPAAqP,CACtP;KACJ;IACD,YAAY,EAAE,cAAc,CAAC,KAAK;IAClC,WAAW,EAAE,SAAS;IACtB,GAAG,EAAE,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC;CAC1E,CAAC,CAAC"}

package/dist/server/tools-lookup.js

@@ -0,0 +1,180 @@
+/** Lookup and search tools: health, search, registers, KERNAL, memory map, opcodes, PAL/NTSC. */
+import { z } from "zod";
+import { search, lookupRegister, lookupKernal, memoryMap, lookupOpcode, palNtscDiff, } from "../tools/query.js";
+import { health, formatHealth } from "../tools/intelligence.js";
+import { RegisterLookupSchema, KernalLookupSchema, MemoryMapSchema, OpcodeLookupSchema, PalNtscDiffSchema, SearchSchema, } from "../schemas/tool-outputs.js";
+import { defineTool, READ_ONLY } from "./define-tool.js";
+export const healthTool = defineTool({
+    name: "c64_health",
+    title: "Service health",
+    description: `Health check for c64-kb backing services (Qdrant vector store, FalkorDB graph, Ollama embeddings, SQLite analytics).
+
+Guidelines: Call this before any other tool when a session begins or after suspected service hiccups. The result indicates whether vector search is available (Ollama OK = vector mode; DEGRADED = keyword-only fallback).
+
+Limitations: Reports current liveness only. Does not validate data freshness or detect partial ingest failures.
+
+Returns a markdown table with one row per service. Expected length: ~6 lines.
+
+Example: {} — no arguments.`,
+    inputSchema: {},
+    annotations: READ_ONLY,
+    run: async () => ({ text: formatHealth(await health()) }),
+});
+export const searchTool = defineTool({
+    name: "c64_search",
+    title: "Search the C64 knowledge base",
+    description: `Semantic + keyword hybrid search across the entire C64 knowledge base. Returns ranked documentation chunks with confidence badges (HIGH/MEDIUM/LOW based on cosine similarity score).
+
+Guidelines: Use for fuzzy intent ("how does badline timing work?", "which chip handles joystick?") or when the user's question doesn't map cleanly to a register, KERNAL routine, or opcode. For known identifiers, prefer c64_lookup_register / c64_lookup_kernal / c64_lookup_opcode which return structured data.
+
+Limitations: Quality depends on Ollama availability. Without Ollama, falls back to Qdrant's full-text index (no semantic similarity). Indexed corpus is stock C64 only (no Mega65 / SuperCPU / cartridge-specific docs).
+
+Param notes: 'limit' defaults to 5; raise for survey-style queries, lower for tight follow-ups. 'filter_source' is an exact-match source filename (e.g. "vic-ii-reference.md").
+
+Expected length: 5-30 chunks of ~100-300 words each in the markdown view; structuredContent has the same hits as typed JSON.
+
+Example: {"query": "stable raster IRQ", "limit": 3} returns the top-3 chunks across all docs.`,
+    inputSchema: {
+        query: z.string().describe("Natural-language query about C64 development"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(20)
+            .optional()
+            .default(5)
+            .describe("Max results to return (1-20, default 5)"),
+        filter_source: z
+            .string()
+            .optional()
+            .describe("Restrict to an exact source file (e.g. 'vic-ii-reference.md')"),
+    },
+    outputSchema: SearchSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ query, limit, filter_source }) => search(query, limit, filter_source),
+});
+export const lookupRegisterTool = defineTool({
+    name: "c64_lookup_register",
+    title: "Look up a hardware register",
+    description: `Look up a Commodore 64 hardware register by canonical name, mnemonic, or hex address. Returns the register's chip, R/W status, aliases, and the top 3 most relevant documentation chunks.
+
+Guidelines: Use this when you know a specific register identifier (e.g. "D011", "SCROLY", "$D011") and want its semantics. For fuzzy intent ("which register controls scrolling?"), use c64_search instead.
+
+Limitations: Stock C64 only (no Mega65/SuperCPU registers). Custom expansion-cartridge registers at $DE00-$DFFF are not documented.
+
+Param notes: 'name_or_addr' accepts canonical name (SCROLY), short mnemonic (D011), or hex address ($D011 / D011). The lookup matches all three forms via aliases.
+
+Expected length: 1 register header + up to 3 doc chunks (~200-500 words total).
+
+Example: {"name_or_addr": "D011"} or {"name_or_addr": "$D011"} or {"name_or_addr": "SCROLY"} — all three resolve to the same register.
+
+Returns structured: {name, address, chip, rw, aliases, documentation[]}.`,
+    inputSchema: {
+        name_or_addr: z
+            .string()
+            .describe("Register name (e.g. 'SCROLY'), mnemonic (e.g. 'D011'), or hex address ($D011 / D011)"),
+    },
+    outputSchema: RegisterLookupSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ name_or_addr }) => lookupRegister(name_or_addr),
+});
+export const lookupKernalTool = defineTool({
+    name: "c64_lookup_kernal",
+    title: "Look up a KERNAL routine",
+    description: `Look up a KERNAL ROM routine by canonical name (e.g. 'CHROUT') or jump-table address (e.g. '$FFD2'). Returns the routine's description, pairs-with partners (e.g. OPEN/CLOSE, CHKIN/CLRCHN), and the top 3 most relevant documentation chunks.
+
+Guidelines: Use when you know a KERNAL routine identifier. For "what KERNAL routine should I call to print a string?", use c64_search.
+
+Limitations: Stock C64 KERNAL only. JiffyDOS / Final Cartridge / SpeedDOS KERNAL extensions are not indexed.
+
+Param notes: 'name_or_addr' is case-insensitive. Hex addresses accept '$FFD2', 'FFD2', or 'ffd2'.
+
+Expected length: 1 routine header + pairs list + up to 3 doc chunks (~200-400 words total).
+
+Example: {"name_or_addr": "CHROUT"} or {"name_or_addr": "$FFD2"}.
+
+Returns structured: {name, address, description, pairs_with[], documentation[]}.`,
+    inputSchema: {
+        name_or_addr: z.string().describe("KERNAL routine name (CHROUT) or jump-table address ($FFD2 / FFD2)"),
+    },
+    outputSchema: KernalLookupSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ name_or_addr }) => lookupKernal(name_or_addr),
+});
+export const memoryMapTool = defineTool({
+    name: "c64_memory_map",
+    title: "Memory map for an address",
+    description: `Given a hex address, return the memory region(s) the address lives in. Correctly reports banked overlap — e.g. $D011 is BOTH "I/O area" AND "VIC-II registers" depending on the bank-switching state of $01.
+
+Guidelines: Use to disambiguate "what is at this address?" when reading existing C64 code. For lookups by region name, query the c64://memory-map resource directly.
+
+Limitations: Returns documented stock-C64 regions only. Doesn't model the full bank-switching matrix; only flags which regions overlap.
+
+Param notes: 'addr' accepts '$D011', 'D011', or 'd011'. Non-hex characters are stripped.
+
+Expected length: Header + 1-3 region rows.
+
+Example: {"addr": "$D011"} returns both the I/O area and VIC-II register entries.
+
+Returns structured: {address, regions[{name, start, end, default_use, bank_switchable}]}.`,
+    inputSchema: {
+        addr: z.string().describe("Hex address (e.g. '$D011', 'D011'). Non-hex characters stripped."),
+    },
+    outputSchema: MemoryMapSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ addr }) => memoryMap(addr),
+});
+export const lookupOpcodeTool = defineTool({
+    name: "c64_lookup_opcode",
+    title: "Look up a 6510 opcode",
+    description: `Look up a 6510 opcode by byte (e.g. '$A9') or by mnemonic (e.g. 'LDA'). Returns cycles, flag effects, page-cross penalty, and a description from the 6510-cpu-reference (legal opcodes) or 6502-illegal-opcodes (undocumented opcodes) reference docs.
+
+Guidelines: For a byte lookup, expect the single matching opcode at the top. For a mnemonic, expect all addressing-mode variants (e.g. 'LDA' returns LDA #imm, LDA $zp, LDA $nnnn,X, etc.).
+
+Limitations: HuC6280 / 65C02 extensions are not indexed. Illegal opcode behavior reported is the most-commonly-cited consensus (some illegals are bus-dependent and vary by chip revision).
+
+Param notes: 'byte_or_mnemonic' accepts '$A9', 'A9', or 'LDA' (case-insensitive).
+
+Expected length: Up to 3 doc chunks (~150-400 words total).
+
+Example: {"byte_or_mnemonic": "$A9"} returns LDA #imm. {"byte_or_mnemonic": "LDA"} returns all LDA variants.
+
+Returns structured: {query, results[{source, section, text, score}]}.`,
+    inputSchema: {
+        byte_or_mnemonic: z.string().describe("Opcode byte ($A9, A9) or mnemonic (LDA, lda)"),
+    },
+    outputSchema: OpcodeLookupSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ byte_or_mnemonic }) => lookupOpcode(byte_or_mnemonic),
+});
+export const palNtscDiffTool = defineTool({
+    name: "c64_pal_ntsc_diff",
+    title: "PAL vs NTSC differences",
+    description: `Compare PAL vs NTSC for a topic. Always returns the canonical region property table (refresh Hz, lines/frame, cycles/line for both PAL and NTSC) plus topic-specific documentation chunks.
+
+Guidelines: Use to surface region-dependent behavior — timing, music tempo, raster mechanics, badline behavior, SID clock. The structured 'regions' array is identical regardless of topic; the 'documentation' array narrows the discussion.
+
+Limitations: PAL-N (Argentina/Brazil) and SECAM are not modeled. Drean PAL-B variant is treated as standard PAL.
+
+Param notes: 'topic' is freeform — short keywords work best ("badline", "music tempo", "SID clock").
+
+Expected length: Region table + up to 3 topic chunks (~200-500 words total).
+
+Example: {"topic": "badline"} returns the timing table plus badline-specific docs.
+
+Returns structured: {topic, regions[], documentation[]}.`,
+    inputSchema: {
+        topic: z
+            .string()
+            .describe("Topic to compare (e.g. 'raster timing', 'music tempo', 'badline', 'SID clock')"),
+        region: z
+            .enum(["pal", "ntsc", "both"])
+            .optional()
+            .default("both")
+            .describe("Limit discussion to a single region (default 'both')"),
+    },
+    outputSchema: PalNtscDiffSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ topic, region }) => palNtscDiff(topic, region),
+});
+//# sourceMappingURL=tools-lookup.js.map

package/dist/server/tools-lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-lookup.js","sourceRoot":"","sources":["../../src/server/tools-lookup.ts"],"names":[],"mappings":"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"}

package/dist/server/tools-maintenance.js

@@ -0,0 +1,116 @@
+/** Tools that report on or change the knowledge base itself: ingest, coverage, link suggestions, gap reports. */
+import { z } from "zod";
+import { ingestDoc } from "../tools/hydrate.js";
+import { coverage, suggestLinks, reportGap } from "../tools/selfimprovement.js";
+import { CoverageSchema, SuggestLinksSchema, ReportGapSchema } from "../schemas/tool-outputs.js";
+import { defineTool, READ_ONLY } from "./define-tool.js";
+import { definedOnly } from "./defined-only.js";
+/**
+ * c64_ingest_doc writes the page under docs/ and replaces that page's chunks
+ * in Qdrant and its entities in the graph. Replacing an existing page's text
+ * is a destructive update in the MCP spec's sense; the same call twice leaves
+ * the same state.
+ */
+const INGEST_DOC = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+/** c64_report_gap inserts a gap row or increments its hit count in SQLite: additive, and not idempotent. */
+const REPORT_GAP = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+};
+export const ingestDocTool = defineTool({
+    name: "c64_ingest_doc",
+    title: "Add or update a document",
+    description: `Add or update a single knowledge-base document. Writes the content to the file under docs/ (creating or replacing it), removes the page's old chunks, and upserts the new chunked content into Qdrant (dense embeddings + sparse BM25 vector) and its entities into the graph.
+
+Guidelines: Use to land new reference material from authoritative sources (codebase 64 manual, VIC-II articles, etc.). Re-running for an existing path replaces that page's chunks. Graph edges are merged, never removed: if the update drops a metadata line, run a clean re-ingest to remove the edge it asserted.
+
+Limitations: Cannot refit the BM25 vocabulary on the fly (that would invalidate every existing sparse vector). New tokens introduced by this doc contribute only to the dense vector. Run a full clean re-ingest to incorporate new vocabulary into BM25.
+
+Param notes: 'path' is absolute or relative to docs/, and must resolve inside docs/. 'content' is the full markdown body (frontmatter optional).
+
+Expected length: Single-line summary, e.g. "Ingested 14 chunks from hardware/foo.md."
+
+Example: {"path": "/abs/path/docs/hardware/sid-tricks.md", "content": "# SID tricks\\n..."}`,
+    inputSchema: {
+        path: z
+            .string()
+            .describe("Path of the markdown file, absolute or relative to docs/; must resolve inside docs/"),
+        content: z.string().describe("Full markdown content (body, optionally with frontmatter)"),
+    },
+    annotations: INGEST_DOC,
+    run: async ({ path: p, content }) => ({ text: await ingestDoc(p, content) }),
+});
+export const coverageTool = defineTool({
+    name: "c64_coverage",
+    title: "Knowledge-base coverage snapshot",
+    description: `Snapshot of c64-kb coverage across categories. Returns per-category counts (techniques, pitfalls, recipes by toolchain), KERNAL coverage stats, total graph + Qdrant size, and the top 10 unresolved gaps. Use to assess KB completeness or to inform ingest priorities.
+
+Inputs: none.
+
+Output: structured CoverageOutput with dimensions, totals, recent_gaps, generated_at. Plus a markdown text rendering.
+
+Example: {}`,
+    inputSchema: {},
+    outputSchema: CoverageSchema.shape,
+    annotations: READ_ONLY,
+    run: () => coverage(),
+});
+export const suggestLinksTool = defineTool({
+    name: "c64_suggest_links",
+    title: "Suggest missing graph edges",
+    description: `Heuristic suggestions for missing edges in the knowledge graph. Compares each entity's doc-chunk text against existing graph edges and flags probable misses (e.g., Technique whose body mentions a Register without a USES edge). v1 is regex-based; surfaces obvious misses, not exhaustive review.
+
+Inputs:
+  - kind (optional): "technique-register" | "recipe-technique" | "pitfall-technique" | "all" (default "all")
+  - limit (optional): max suggestions to return (1-100, default 20)
+
+Output: structured SuggestLinksOutput with suggestions[], generated_at. Suggestion kinds: technique_uses_register, recipe_implements_technique, pitfall_triggered_by_technique, pitfall_mitigated_by_technique. "pitfall-technique" emits the last two: a technique named in a pitfall's Fix section is proposed as MITIGATED_BY, one named elsewhere in the pitfall as TRIGGERED_BY.
+
+Example: {"kind": "technique-register", "limit": 10}`,
+    inputSchema: {
+        kind: z
+            .enum(["technique-register", "recipe-technique", "pitfall-technique", "all"])
+            .default("all")
+            .describe('Edge kind to check: "technique-register" | "recipe-technique" | "pitfall-technique" | "all"'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(20)
+            .describe("Max suggestions to return (1-100, default 20)"),
+    },
+    outputSchema: SuggestLinksSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ kind, limit }) => suggestLinks({ kind, limit }),
+});
+export const reportGapTool = defineTool({
+    name: "c64_report_gap",
+    title: "Report a knowledge gap",
+    description: `Record a query that produced no useful result, so the gap surfaces in c64_coverage and (later) the dashboard backlog. Agents should call this when they searched but couldn't ground their answer.
+
+Inputs:
+  - query (required): the query that returned nothing useful
+  - tool_called (optional): which c64_kb tool was used
+  - notes (optional): freeform observation about what's missing
+
+Output: structured ReportGapOutput with gap_id, hit_count, status (new|incremented), and a human-readable message.
+
+Example: {"query": "stable raster IRQ on REU-attached systems", "tool_called": "c64_search", "notes": "no REU coverage in the KB"}`,
+    inputSchema: {
+        query: z.string().min(1).describe("The query that returned nothing useful"),
+        tool_called: z.string().optional().describe("Which c64_kb tool was used (e.g. c64_search)"),
+        notes: z.string().optional().describe("Freeform observation about what is missing"),
+    },
+    outputSchema: ReportGapSchema.shape,
+    annotations: REPORT_GAP,
+    run: ({ query, tool_called, notes }) => reportGap({ query, ...definedOnly({ tool_called, notes }) }),
+});
+//# sourceMappingURL=tools-maintenance.js.map

package/dist/server/tools-maintenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-maintenance.js","sourceRoot":"","sources":["../../src/server/tools-maintenance.ts"],"names":[],"mappings":"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"}

package/dist/server/tools-pitfalls.js

@@ -0,0 +1,89 @@
+/** Pitfall, lint and failure-diagnosis tools. */
+import { z } from "zod";
+import { pitfallsFor, failureDiagnose } from "../tools/pitfalls.js";
+import { lintSourceResult } from "../tools/lint.js";
+import { PitfallsForSchema, FailureDiagnoseSchema, LintSourceSchema } from "../schemas/tool-outputs.js";
+import { defineTool, READ_ONLY } from "./define-tool.js";
+import { definedOnly } from "./defined-only.js";
+export const pitfallsForTool = defineTool({
+    name: "c64_pitfalls_for",
+    title: "Pitfalls for a register, routine or technique",
+    description: `Look up C64 coding pitfalls connected to a specific Register, KERNAL routine, or Technique. Returns all Pitfall nodes that have a TRIGGERED_BY edge to the named entity — and, for a Technique, those with a MITIGATED_BY edge to it, i.e. pitfalls whose Fix is that technique — ordered by severity (critical → high → medium → low).
+
+Purpose: Surfaces the gotchas a developer will hit when using a particular register, routine, or technique, and the pitfalls a technique exists to cure. Intended as a proactive "what can go wrong?" check before implementing a technique.
+
+Inputs: 'topic' is the entity name to look up. The tool tries three interpretations in order: (1) Register — matched by canonical name, hex address, or alias (e.g. "D012", "$D012"); (2) KernalRoutine — matched by canonical name (e.g. "CHROUT"); (3) Technique — matched by snake_case name (e.g. "stable_raster_irq"). The first interpretation that returns at least one Pitfall wins.
+
+Output: {topic, topic_kind, pitfalls[{name, title, severity, region, category, triggered_by[], mitigated_by[]}]}. topic_kind is the winning interpretation (Register | KernalRoutine | Technique) or "search" if no direct match was found. pitfalls is ordered severity-descending. Each pitfall's triggered_by list contains all entities that trigger it, not just the queried entity; mitigated_by lists the techniques whose application is its Fix (CONVENTIONS-pitfalls.md **Mitigated by techniques:**). Read the two lists separately: sprite_dma_overflow is triggered by a naive multiplexer and mitigated by a correct one.
+
+When no direct match is found, topic_kind is "search" and pitfalls is empty. Use c64_search or c64_technique_lookup to explore related content.
+
+Examples: {"topic": "D012"} → pitfalls triggered by $D012 (raster line register). {"topic": "stable_raster_irq"} → pitfalls triggered by, or fixed by, the stable-raster-IRQ technique. {"topic": "pal_ntsc_detection"} → the three region-timing pitfalls it is the remedy for. {"topic": "CHROUT"} → pitfalls triggered by the KERNAL CHROUT routine.
+
+See also: c64_failure_diagnose to match symptoms to known failure patterns. c64_technique_lookup for a technique's full profile (registers, KERNAL calls, recipes).
+
+Limitations: Returns only pitfalls indexed in Phase 5 (28 nodes across 8 categories). Topics with no direct graph match fall back to "search" — run c64_search for fuzzy queries.`,
+    inputSchema: {
+        topic: z
+            .string()
+            .describe("Register name (D012, $D012), KERNAL routine (CHROUT), or technique name (stable_raster_irq)"),
+    },
+    outputSchema: PitfallsForSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ topic }) => pitfallsFor(topic),
+});
+export const lintSourceTool = defineTool({
+    name: "c64_lint_source",
+    title: "Lint C or 6502 source against pitfall rules",
+    description: `Run the knowledge base's pitfall rules over a piece of your own C (Oscar64) or 6502 assembly source. Each rule is compiled from one pitfall or recipe page and points back at it: sid_write_only_registers (a read or read-modify-write of $D400-$D418), cia1_ddr_cleared_kills_keyboard (a store of 0 to $DC02 with no later $FF), empty_name_open_15_hangs_on_read (an empty-name OPEN of channel 15 followed by a read; from the high-score recipe's warning, and the two pages that speak to it disagree, so the finding is heuristic and says so), raster_poll_with_kernal_irq_live (a $D012 busy-wait in a file that never installs an interrupt), lfsr_zero_state_lockup (a zero seed the file shifts or XORs), decimal_mode_in_irq_handler (assembly only: an installed handler that reaches ADC or SBC before any CLD), d016_unmasked_rmw_clobbers_csel_mcm (a $D016 store not derived from a masked read) and jmp_indirect_page_boundary_bug (JMP ($xxFF)).
+
+Purpose: a self-check an agent runs on the code it just wrote, before building it. No graph or vector store is needed; the rules are text patterns.
+
+Inputs: 'source' is the file text. 'language' is "c", "asm" or "auto" (default; detected from preprocessor lines and statement shape). 'toolchain' is optional and only recorded in the output.
+
+Output: {language, toolchain?, findings[{rule, pitfall, line, excerpt, message, page, certainty}], summary}. 'certainty' is "definite" (the pattern is the pitfall by construction), "likely" (it is the pitfall unless something outside the file excuses it, such as an earlier named OPEN) or "heuristic" (the pattern often accompanies the pitfall; read the page and decide). 'page' is the repo path of the pitfall or recipe the rule was compiled from, with the pitfall's H2 as the anchor when the source is a pitfall page; 'pitfall' is the pitfall node the rule stands for, or for empty_name_open_15_hangs_on_read the name of the recipe warning it compiles, which is not a pitfall node. 'summary' is one line. Read the message: each uses the page's own words for the mechanism and the fix.
+
+Limitations: one file at a time, so an interrupt installed in another file makes the raster-poll rule fire as a heuristic; a shadow variable the lint cannot recognise makes the $D016 rule fire as a heuristic. Symbolic operands (JMP (vector)) are not resolved. Silence is not a pass: the rules cover the pitfalls listed above and no others.
+
+See also: c64_pitfalls_for for every pitfall a register, routine or technique triggers, most of which have no text pattern to lint.`,
+    inputSchema: {
+        source: z.string().describe("The source text to lint (one file)"),
+        language: z
+            .enum(["c", "asm", "auto"])
+            .default("auto")
+            .describe("c (Oscar64/cc65 C), asm (6502 assembly), or auto"),
+        toolchain: z
+            .string()
+            .optional()
+            .describe("Toolchain name, recorded in the output (e.g. oscar64, kickassembler)"),
+    },
+    outputSchema: LintSourceSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ source, language, toolchain }) => lintSourceResult(source, { language, ...definedOnly({ toolchain }) }),
+});
+export const failureDiagnoseTool = defineTool({
+    name: "c64_failure_diagnose",
+    title: "Diagnose a failure from its symptom",
+    description: `Given a symptom description (e.g. "black screen", "sprites flicker every other frame"), find matching CrashPattern nodes from the Phase 5 failure-pattern catalog. Returns up to 5 patterns ranked by keyword overlap, each with its description, likely causes, diagnosis steps, and CAUSED_BY graph edges.
+
+Purpose: Lets an agent or developer describe what they observe and get back structured failure-pattern data: what is probably broken, what graph entities cause it, and how to diagnose it.
+
+Inputs: 'symptom' is a free-form description of the observed failure. Short keyword phrases work well ("black screen", "music wrong tempo", "sprites disappear"). The tool tokenizes the query and scores each CrashPattern's symptom slug + description + likely_causes field by token overlap. Tokens shorter than 3 characters are ignored.
+
+Output: {query, matches[{symptom, description, likely_causes[], diagnosis_steps, caused_by[], relevance}]}. matches is ordered by relevance score (0-1). An empty matches array means no patterns scored above zero — try rephrasing with different keywords.
+
+Examples: {"symptom": "black screen"} → matches black_screen pattern (relevance ~1.0). {"symptom": "sprites flicker every other frame"} → matches sprite_flicker_periodic and/or sprite_flicker_random. {"symptom": "music plays too fast"} → matches wrong_music_tempo.
+
+See also: c64_pitfalls_for to look up pitfalls proactively before they occur. c64_search for broad documentation queries.
+
+Limitations: Scoring is token-overlap only — no semantic similarity. Uncommon symptom phrasings may score poorly. Phase 5 covers 15 CrashPattern nodes. Future phases add more patterns.`,
+    inputSchema: {
+        symptom: z
+            .string()
+            .describe("Description of the observed failure (e.g. 'black screen', 'sprites flicker every other frame', 'music wrong tempo')"),
+    },
+    outputSchema: FailureDiagnoseSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ symptom }) => failureDiagnose(symptom),
+});
+//# sourceMappingURL=tools-pitfalls.js.map

package/dist/server/tools-pitfalls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-pitfalls.js","sourceRoot":"","sources":["../../src/server/tools-pitfalls.ts"],"names":[],"mappings":"AAAA,iDAAiD;AAEjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACxG,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;IACxC,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,+CAA+C;IACtD,WAAW,EAAE;;;;;;;;;;;;;;kLAcmK;IAChL,WAAW,EAAE;QACX,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,CACP,6FAA6F,CAC9F;KACJ;IACD,YAAY,EAAE,iBAAiB,CAAC,KAAK;IACrC,WAAW,EAAE,SAAS;IACtB,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC;CACvC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;IACvC,IAAI,EAAE,iBAAiB;IACvB,KAAK,EAAE,6CAA6C;IACpD,WAAW,EAAE;;;;;;;;;;oIAUqH;IAClI,WAAW,EAAE;QACX,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QACjE,QAAQ,EAAE,CAAC;aACR,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;aAC1B,OAAO,CAAC,MAAM,CAAC;aACf,QAAQ,CAAC,kDAAkD,CAAC;QAC/D,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,sEAAsE,CAAC;KACpF;IACD,YAAY,EAAE,gBAAgB,CAAC,KAAK;IACpC,WAAW,EAAE,SAAS;IACtB,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,CACvC,gBAAgB,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,GAAG,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;CACxE,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;IAC5C,IAAI,EAAE,sBAAsB;IAC5B,KAAK,EAAE,qCAAqC;IAC5C,WAAW,EAAE;;;;;;;;;;;;yLAY0K;IACvL,WAAW,EAAE;QACX,OAAO,EAAE,CAAC;aACP,MAAM,EAAE;aACR,QAAQ,CACP,qHAAqH,CACtH;KACJ;IACD,YAAY,EAAE,qBAAqB,CAAC,KAAK;IACzC,WAAW,EAAE,SAAS;IACtB,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,eAAe,CAAC,OAAO,CAAC;CAC/C,CAAC,CAAC"}