@vpxa/aikit 0.1.254 → 0.1.255

package/scaffold/dist/definitions/protocols.mjs

@@ -50,9 +50,9 @@ Use AI Kit retrieval/compression first. Native tools are fallback only.
 | NEVER use this | USE THIS instead | Why |
 |---|---|---|
 | \`read_file\` to understand a file | \`file_summary({ path })\` | Structure first |
-| \`read_file\` to find code | \`compact({ path, query })\` | Focused extract |
+| \`read_file\` to find code | \`compact({ path, query })\` | Fresh compression: \`compact({ path, query })\`; \`query\` is required unless \`ref\` is supplied |
 | Multiple \`read_file\` calls | \`digest({ sources, query: "<task description>" })\` | Compress multi-file context |
-| Cached ref to refocus prior output | \`compact({ ref, query? })\` | Reuse reversible text artifacts |
+| Cached ctxc ref to refocus prior output | \`compact({ ref })\` or \`compact({ ref, query? })\` | \`ctxc_...\` values are reversible refs, not ids or file paths |
 | \`grep_search\` / \`semantic_search\` | \`search({ query })\` | Indexed search |
 | \`grep_search\` for a symbol | \`symbol({ name })\` | Def + refs |
 | \`run_in_terminal\` for tsc/lint | \`check({})\` | Narrow validation |
@@ -61,7 +61,7 @@ Use AI Kit retrieval/compression first. Native tools are fallback only.
 | \`get_changed_files\` | \`run_in_terminal\` with \`git diff <specific-file>\` | Diff only target file |
 | \`run_in_terminal\` for code edits | \`replace_string_in_file\` | Avoid shell-edit loops |
 
-> **Path Note:** \`compact({path})\` and \`file_summary({path})\` accept any absolute path.
+> **Path Note:** \`compact({ path, query })\` and \`file_summary({ path })\` accept any absolute path. Cached \`ctxc_...\` values are reversible refs passed as \`ref\` to \`compact({ ref })\` or \`compact({ ref, query? })\`; do not invent a separate \`read\`/\`id\` contract.
 
 **\`read_file\` is ONLY for exact edit lines.** Use \`file_summary\` or \`compact\` first.
 

package/scaffold/dist/definitions/skills/aikit.mjs

@@ -155,9 +155,9 @@ Every tool call passes through extractors that capture reusable facts:
 | **Research results** | \`web_search\`, \`web_fetch\`, \`search\`, \`find\` | Search findings, web content, code discoveries |
 | **Behavioral patterns** | ALL tools (ring buffer) | Tool preferences, search→edit sequences, error-fix cycles |
 
-**Retrieval:** Use \`enrich: true\` on any tool that supports it — the server automatically surfaces previously captured facts relevant to your query. Search/find/knowledge responses can also emit reusable refs; feed those into \`compact({ ref, query })\` instead of reopening the source.
+**Retrieval:** Use \`enrich: true\` on any tool that supports it — the server automatically surfaces previously captured facts relevant to your query. Search/find/knowledge responses can also emit reusable \`ctxc_...\` refs; pass them as \`ref\` to \`compact({ ref })\` or \`compact({ ref, query? })\` instead of reopening the source. \`ctxc_...\` is a reversible ref, not an id or path.
 
-**Best practice:** Before re-reading a file you've already explored, try \`search({ query: "file-path-or-topic" })\` — auto-knowledge may already have what you need, or reuse an existing \`ref\` with \`compact({ ref, query })\`.
+**Best practice:** Before re-reading a file you've already explored, try \`search({ query: "file-path-or-topic" })\` — auto-knowledge may already have what you need, or reuse an existing \`ctxc_...\` ref with \`compact({ ref })\` or \`compact({ ref, query? })\`.
 
 ### Retention & Tier Promotion
 - Memories start at **working** tier → promote on repeated access: episodic (2) → semantic (5) → procedural (10)