knowy-cli 0.1.2

package/skills/knowy-judge/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: knowy-judge
+description: Cross-check knowledge files for consistency, coherence, and project alignment
+user-invokable: true
+argument-hint: "[scope: file name, file pair, or event description]"
+---
+
+# Knowy Judge
+
+Verify that the three knowledge files (principles, vision, experience) are internally sound, consistent with each other, and aligned with the actual project state.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Governance Principles
+
+These rules govern how you interact with knowledge files. Follow them in every check:
+
+- **Principles are the highest authority.** If vision or experience conflicts with principles, the pressure is on vision/experience to change — unless the conflict reveals that a principle needs revision.
+- **Vision evolves with understanding.** It should be updated after milestones, not frozen.
+- **Experience is distilled, not accumulated.** Only patterns that influence future decisions belong here. Raw events go in history/.
+- **Knowledge files are indexes, not encyclopedias.** Each should be short enough to read in one pass (~100-200 lines). Long content belongs in subdirectories.
+- **Never modify files without explicit user confirmation.** Present findings and suggestions; let the user decide.
+
+## Workflow
+
+### 1. Read knowledge files
+
+Read all three core files:
+- `.knowledge/principles.md`
+- `.knowledge/vision.md`
+- `.knowledge/experience.md`
+
+Also scan `.knowledge/research/`, `.knowledge/design/`, `.knowledge/history/` for additional context.
+
+### 2. Read project context
+
+To check alignment with the actual project, also examine:
+- Project directory structure (what files and directories exist)
+- `package.json`, `Cargo.toml`, or equivalent (tech stack, dependencies)
+- Recent git log (what has actually been built recently)
+- README or other top-level docs
+
+### 3. Determine scope
+
+Parse `$ARGUMENTS` to decide what to check:
+
+- **No arguments**: full check (all 17 sections below)
+- **Single file** (e.g., "experience"): that file's self-consistency, internal coherence, project alignment, and its cross-references with the other two files
+- **File pair** (e.g., "principles vision"): the 2 directional cross-references for that pair
+- **Event description** (e.g., "just finished the auth system"): impact analysis on all three files
+
+### 4. Execute checks
+
+#### A. Self-consistency (3 checks)
+
+For each file, check its structural and logical integrity:
+
+**Principles:**
+- Does the root axiom exist and is it clearly stated?
+- Does every derived principle trace back to the root axiom or another principle? Are there broken derivation chains?
+- Are there principles that say the same thing in different words (redundancy)?
+- Is the document organized from general to specific?
+
+**Vision:**
+- Does the problem statement clearly define who has the problem and why?
+- Does the roadmap flow logically? Are prerequisites respected?
+- Are milestones mutually exclusive or do they overlap?
+- Are success criteria concrete and verifiable?
+
+**Experience:**
+- Does each lesson follow the pattern/event/takeaway format?
+- Are there lessons that contradict each other without acknowledging the contradiction?
+- Are lessons specific enough to be actionable?
+- Are source references present and traceable?
+
+#### B. Internal Coherence (3 checks)
+
+For each file, check for contradictions in content:
+
+- Are there statements that directly contradict each other?
+- Are there implicit assumptions that conflict?
+- Are there outdated entries that no longer reflect the project's reality?
+
+#### C. Cross-references (6 directional checks)
+
+Each direction asks a specific question:
+
+| Direction | Core Question | Detailed Probes |
+|-----------|--------------|-----------------|
+| Principles → Vision | Can the vision be derived from the principles? | Does each roadmap item serve at least one principle? Are there vision items with no principled justification? |
+| Vision → Principles | Does the vision require principles that aren't stated? | Are there implicit assumptions in the vision that should be made explicit as principles? |
+| Principles → Experience | Do the principles predict the patterns observed? | Has experience validated the principles? Which principles lack empirical support? |
+| Experience → Principles | Does any experience challenge or extend the principles? | Are there lessons that suggest a principle is wrong, incomplete, or needs nuance? |
+| Vision → Experience | Does experience support the planned direction? | Are there known risks from experience that the vision doesn't address? Has the vision learned from past failures? |
+| Experience → Vision | Are there lessons suggesting opportunities not yet in the vision? | Has experience revealed capabilities or patterns that could open new directions? |
+
+#### D. Project Alignment (3 checks)
+
+Check each file against the actual project state:
+
+**Principles vs Project:**
+- Do claimed technology choices match actual dependencies?
+- Do architectural principles match the actual code structure?
+- Are there principles about practices (e.g., "TDD") that aren't actually followed?
+
+**Vision vs Project:**
+- Does the roadmap status match what's actually implemented?
+- Are "completed" milestones truly complete in the code?
+- Are there significant implemented features not reflected in the vision?
+- Does the tech stack in the vision match the actual project?
+
+**Experience vs Project:**
+- Are referenced files/features still present in the project?
+- Have lessons been acted upon? (e.g., "always validate first" — is validation actually in place?)
+- Are there stale lessons about problems that have been solved or code that was rewritten?
+
+#### E. Overall (1 check)
+
+Synthesize all findings:
+- Where is the most pressure? Which file needs the most attention?
+- Is the knowledge system generally healthy or in need of significant work?
+- What is the single most impactful action the user could take?
+
+#### F. Beyond Scope (1 check)
+
+Look for content that doesn't belong:
+- Lessons about a different project or domain
+- Principles too generic to be useful (e.g., "write clean code")
+- Vision items that belong in a separate project
+- Content that should be in subdirectories instead of core files
+
+### 5. Format output
+
+```markdown
+## Knowledge Health Check
+
+### Self-consistency
+🟢 Principles — root axiom present, derivation chains intact.
+🟡 Vision — Phase 3 and Phase 5 overlap in scope.
+   Phase 3 (line 45): "Implement caching layer"
+   Phase 5 (line 67): "Add performance optimization including caching"
+   → Clarify the boundary or merge these phases.
+🟢 Experience — all lessons follow consistent format.
+
+### Internal Coherence
+🟢 Principles — no contradictions.
+🟡 Vision — current state section says "auth is complete" (line 28)
+   but roadmap still lists auth as pending (line 52).
+   → Update one or the other.
+🟢 Experience — consistent.
+
+### Cross-references
+🟢 Principles → Vision — vision is derivable from principles.
+🟡 Vision → Principles — vision mentions "progressive disclosure"
+   but principles don't include a related principle.
+   → Add a principle, or document this as a tactical choice in vision.
+🟢 Principles → Experience — principles predict observed patterns.
+🟢 Experience → Principles — no challenges to existing principles.
+🔴 Vision → Experience — vision plans to use SSR, but experience
+   recorded SSR hydration issues.
+   Vision line 34: "Phase 2: migrate to SSR"
+   Experience line 12: "SSR hydration caused 3-day debug cycle"
+   → Address this known risk in vision, or explain why context differs.
+🟢 Experience → Vision — no missed opportunities.
+
+### Project Alignment
+🟢 Principles — tech choices match project reality.
+🟡 Vision — roadmap says Phase 1 complete, but tests/ directory
+   is empty. Success criteria mentions "90% test coverage."
+   → Either update success criteria or add tests.
+🟢 Experience — all referenced code still exists.
+
+### Overall
+🟡 Generally healthy. Main pressure on vision.md — one conflict
+   with experience, one internal inconsistency, and one alignment
+   gap with project state.
+
+### Beyond Scope
+🟢 All content is relevant to this project.
+
+## Suggested Actions
+1. [High] Resolve SSR conflict between vision and experience
+2. [Medium] Fix auth status inconsistency in vision
+3. [Medium] Clarify Phase 3/5 overlap in vision
+4. [Low] Consider adding progressive disclosure principle
+```
+
+### 6. Event-based analysis (when $ARGUMENTS describes an event)
+
+```markdown
+## Post-feature Check: [Event]
+
+### Impact on Experience
+🟡 Worth distilling — [specific observation].
+   → Suggest adding a lesson to experience.md
+
+### Impact on Vision
+🟢 Milestone completed as planned.
+   → Mark as complete in roadmap.
+
+### Impact on Principles
+🟢 No challenge to existing principles.
+
+### Project Alignment
+🟡 Feature is implemented but vision hasn't been updated.
+
+### Suggested Actions
+1. Add lesson to experience.md: [specific lesson]
+2. Update vision.md: mark [milestone] as complete
+```
+
+### 7. Reorganization offer
+
+If checks reveal that files are too disorganized to assess clearly, offer to help reorganize. Common triggers:
+
+- **Overgrown core file** (>200 lines): Propose moving detail to subdirectories, keeping only distilled content in core.
+- **Raw events in experience.md**: Propose moving them to history/ and distilling into patterns.
+- **Stale content**: Propose removing or updating entries that reference deleted code, completed milestones, or resolved problems.
+- **Broken structure**: Propose reordering sections to match template structure (root → derived, general → specific).
+- **Mature subdirectory content**: Propose distilling key insights from research/design/history into the appropriate core file.
+
+Format the offer clearly:
+
+```markdown
+## Reorganization Suggested
+
+experience.md has grown to 280 lines (recommended: ~200).
+- 5 lessons appear to be raw events rather than distilled patterns
+- 3 lessons reference code that has been rewritten
+
+Would you like me to help reorganize?
+- Move raw events to history/
+- Distill remaining lessons into four-part format
+- Remove or update stale references
+```
+
+If the user agrees:
+1. Show proposed changes as diffs for each file, one at a time
+2. Wait for user confirmation before each write
+3. After all changes, run a focused re-check on modified files
+
+### 8. Recursive verification
+
+After the user makes changes based on your suggestions:
+
+1. Re-read the modified files
+2. Run a focused check on the changed areas only
+3. Confirm the changes resolved the issues without introducing new ones
+4. If new issues are found, report them (one recursion only — don't loop)
+
+## Display Rules
+
+- 🟢 **Healthy**: one line, no details needed
+- 🟡 **Tension**: expand with specific quotes (file + line reference), explain the tension, suggest resolution
+- 🔴 **Conflict**: expand with specific quotes, explain the conflict, suggest concrete action with priority
+- Always quote the specific text from knowledge files that supports your finding
+- End with a numbered list of suggested actions, ordered by priority ([High] / [Medium] / [Low])
+
+## Guidelines
+
+- **Language**: Read `.knowy.json` → `language` field (e.g., `"zh-TW"`). Use that language for ALL output — section headers, descriptions, suggestions, everything. If `.knowy.json` is missing or has no language field, detect from conversation context or default to English.
+- Be specific — always quote relevant text from knowledge files
+- Distinguish between true contradictions (🔴) and tensions worth watching (🟡)
+- Don't flag stylistic differences as inconsistencies
+- For Project Alignment checks, actually read project files — don't guess
+- Focus on substance: does the knowledge system help the team make good decisions?
+- Never modify files automatically — only suggest changes
+- After user makes changes, offer to re-check (recursive verification, once)

package/skills/knowy-next/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: knowy-next
+description: Plan the next step based on project knowledge
+user-invokable: true
+argument-hint: "[direction or feature area to explore]"
+---
+
+# Knowy Next
+
+Help the user decide and plan what to work on next, grounded in the project's principles, vision, and experience.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Governance Principles
+
+- **Principles are the highest authority.** Every recommendation must be traceable to a principle. If it isn't, flag it as a pragmatic choice.
+- **Vision is the roadmap.** Follow the established order unless experience provides compelling reason to deviate.
+- **Experience is the guardrail.** Always check for relevant lessons before recommending an approach.
+- **Never auto-invoke other skills.** Only suggest them.
+
+## Workflow
+
+### 1. Read knowledge files
+
+Read all three core files:
+- `.knowledge/principles.md`
+- `.knowledge/vision.md`
+- `.knowledge/experience.md`
+
+Also check:
+- `.knowledge/design/` for relevant design documents
+- Project structure and recent git log for actual state
+
+### 2. Determine direction
+
+**If `$ARGUMENTS` provides a direction** (e.g., "error handling", "mobile support"):
+- Locate it in the vision roadmap
+- Check prerequisites — are prior milestones actually complete? (check code, not just what vision says)
+- Find relevant experience entries (lessons, pitfalls, patterns)
+- Find relevant design documents
+- Check if principles constrain the approach
+
+**If `$ARGUMENTS` is empty**:
+- Look at the vision roadmap for the next incomplete milestone
+- Cross-reference with actual project state (what's really done?)
+- Consider experience lessons that might affect priority
+- Suggest the most logical next step with justification
+
+### 3. Converge
+
+Through conversation with the user, converge on all of these items:
+
+- **Feature name**: short, descriptive
+- **One-line description**: what it delivers to the user/system
+- **Roadmap position**: which phase/milestone it belongs to
+- **Prerequisites**: what must be done first (check if actually done)
+- **Scope**:
+  - What's included (explicit list)
+  - What's explicitly excluded (prevent scope creep)
+- **Grounded in principles**: which principle(s) this serves, and how. Show the derivation chain.
+- **Informed by experience**: relevant lesson(s) and how to apply them. Quote the specific lesson.
+- **Risks**: based on experience, what could go wrong? What mitigation is available?
+- **Success criteria**: how do we know this is done? Make it concrete and verifiable.
+
+### 4. Output
+
+Present a concise feature brief:
+
+```markdown
+## Next: [Feature Name]
+
+**Description**: [One-line description]
+
+**Roadmap**: [Phase/milestone reference]
+
+**Prerequisites**:
+- [x] [Completed prerequisite]
+- [ ] [Missing prerequisite — must be addressed first]
+
+**Scope**:
+- ✅ [Included]
+- ✅ [Included]
+- ❌ [Explicitly excluded]
+
+**Grounded in principles**:
+- Principle: "[quoted principle]"
+- How this feature serves it: [explanation]
+
+**Informed by experience**:
+- Lesson: "[quoted lesson from experience.md]"
+- How to apply: [specific guidance for this feature]
+
+**Risks**:
+- [Known risk from experience] → Mitigation: [approach]
+
+**Success criteria**:
+- [ ] [Concrete, verifiable criterion]
+- [ ] [Concrete, verifiable criterion]
+```
+
+### 5. Suggest next action
+
+After presenting the feature brief, scan the project for spec/planning tools:
+
+- Check `.claude/skills/` for spec-related skills (e.g., `speckit-specify`, `speckit-plan`)
+- Check `.specify/` for Speckit
+- Check `openspec/` for OpenSpec
+- Check `.kiro/specs/` for Kiro Specs
+
+**If a spec tool is found**: suggest the specific command.
+  Example: "You can now use `/speckit-specify` to create a detailed specification for this feature."
+
+**If no spec tool is found**: give a generic prompt.
+  "You can now use your preferred specification tool to flesh out the details, or start implementing directly."
+
+## Guidelines
+
+- **Language**: Read `.knowy.json` → `language` field (e.g., `"zh-TW"`). Use that language for ALL output — section headers, descriptions, suggestions, everything. If `.knowy.json` is missing or has no language field, detect from conversation context or default to English.
+- Keep the feature brief concise — it's a starting point, not a full spec
+- **Every recommendation must reference knowledge files.** Don't invent principles or cite non-existent experience. If there's no relevant principle, say so explicitly.
+- Verify project state before claiming prerequisites are met — check actual code, not just what vision says
+- If the user's direction conflicts with principles or experience, flag it clearly with the specific conflict, but let them decide
+- If the roadmap is empty or unclear, help the user think through priorities rather than guessing
+- Never auto-invoke other skills — only suggest them

package/skills/knowy-update/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: knowy-update
+description: Check knowledge file structure completeness and suggest improvements
+user-invokable: true
+argument-hint: "[specific file or area to check]"
+---
+
+# Knowy Update
+
+Review existing knowledge files against the latest templates, governance principles, and actual project state. Suggest structural improvements.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Governance Principles
+
+- **Principles are the highest authority.** If the structure check reveals that principles are weak or missing derivation chains, this is the highest priority fix.
+- **Vision evolves with understanding.** Suggest updates when the project has moved forward but vision hasn't caught up.
+- **Experience is distilled, not accumulated.** If experience.md is growing too long, suggest distilling. If history/ has entries that should be promoted, flag them.
+- **Knowledge files are indexes, not encyclopedias.** If any core file exceeds ~200 lines, suggest moving detail to subdirectories.
+- **Never modify files without explicit user confirmation.**
+
+## Workflow
+
+### 1. Read current state
+
+- Read `.knowledge/principles.md`, `.knowledge/vision.md`, `.knowledge/experience.md`
+- Read `.knowledge/.templates/` for the latest recommended structure
+- Scan `.knowledge/research/`, `.knowledge/design/`, `.knowledge/history/` for existing files
+- Read project structure and recent git log for context
+
+### 2. Structural check
+
+Compare each core file against its template. Look for:
+
+- **Missing sections**: template suggests a section that the file doesn't have
+- **Empty sections**: section header exists but no content below it
+- **Orphaned content**: content that doesn't fit any recommended section
+- **Overgrown files**: core files exceeding ~200 lines (should move detail to subdirectories)
+- **Weak derivations**: principles without clear derivation chains
+- **Vague milestones**: vision roadmap items without success criteria
+- **Undistilled lessons**: experience entries that are raw events rather than patterns
+
+### 3. Cross-file check
+
+- Do principles reference concepts that aren't in the vision?
+- Does experience mention lessons that should update the vision?
+- Are there subdirectory files mature enough to distill into core files?
+- Is the three-file system coherent as a whole?
+
+### 4. Project alignment check
+
+- Has the project evolved since the knowledge files were last updated?
+- Are there new features, dependencies, or architectural changes not reflected?
+- Does the git log show recent work that should generate experience entries?
+
+### 5. Report
+
+Present findings organized by priority:
+
+```
+## Structure Check
+
+### principles.md
+🟢 Root Axiom — present and clearly stated.
+🟡 Derived Principles — only 1 principle listed, template suggests at least 2-3.
+🔴 Derivation chains — missing. Principles don't trace back to root axiom.
+   → Add "Derived from: [root axiom]" to each principle.
+
+### vision.md
+🟢 Problem Statement — present and specific.
+🟢 Current State — honest and up-to-date.
+🟡 Roadmap — has milestones but no success criteria.
+   → Add concrete success criteria to each milestone.
+
+### experience.md
+🟢 Structure follows template format.
+🟡 Lesson "caching strategy" (line 23) reads like a raw event, not a distilled pattern.
+   → Rewrite using: Theory said X → Actually Y → Solved by Z → Lesson: W
+
+### Subdirectories
+🟡 design/auth-system.md looks mature — consider distilling key decisions into vision.md.
+🟡 history/ has 3 new entries since last experience.md update — review for distillation.
+
+### Project Alignment
+🟡 git log shows 12 commits since last vision update. Phase 2 may be complete.
+   → Verify and update roadmap status.
+
+## Suggested Actions (by priority)
+1. [High] Add derivation chains to principles.md
+2. [Medium] Add success criteria to roadmap milestones
+3. [Medium] Distill recent history/ entries into experience.md
+4. [Low] Review design/auth-system.md for vision.md update
+```
+
+### 6. Reorganization offer
+
+When structural problems are severe enough to warrant reorganization, offer proactively:
+
+- **Overgrown core file** (>200 lines): Propose extracting detail to subdirectories.
+  - principles.md → move research/exploration to research/
+  - vision.md → move detailed designs to design/
+  - experience.md → move raw events to history/, keep only distilled lessons
+- **Wrong format**: Propose reformatting entries to match template structure.
+  - experience lessons not in four-part format (Theory said → Actually → Resolved by → Lesson)
+  - principles without derivation chains
+  - roadmap milestones without success criteria
+- **Stale content**: Propose removing or archiving outdated entries.
+- **Mature subdirectory content**: Propose distilling into core files.
+
+Format:
+
+```markdown
+## Reorganization Suggested
+
+experience.md has grown to 280 lines (recommended: ~200).
+- 5 lessons appear to be raw events → move to history/, distill patterns
+- 3 lessons reference rewritten code → update or archive
+
+Would you like me to help reorganize?
+```
+
+If the user agrees, proceed step by step (one file at a time, show diff, wait for confirmation).
+
+### 7. Assist with changes
+
+- If the user wants to act on any suggestion, help them make the change
+- Before writing, verify the change is consistent with other knowledge files
+- Show diffs before writing
+- After writing, offer a focused re-check on the changed area
+
+## Guidelines
+
+- **Language**: Read `.knowy.json` → `language` field (e.g., `"zh-TW"`). Use that language for ALL output — section headers, descriptions, suggestions, everything. If `.knowy.json` is missing or has no language field, detect from conversation context or default to English.
+- Be constructive, not critical — the goal is to help, not to grade
+- Prioritize by impact: what would help the AI (and the team) most?
+- Don't suggest adding content the user may not have yet — only structural improvements
+- For project alignment, actually read project files — don't guess
+- If you notice the knowledge files are getting stale, say so directly

package/src/adapters/detect.js

@@ -0,0 +1,38 @@
+import { access, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { TOOL_REGISTRY } from './registry.js';
+
+async function checkDetect(projectRoot, check) {
+  const fullPath = join(projectRoot, check.path);
+  try {
+    const s = await stat(fullPath);
+    if (check.type === 'file') return s.isFile();
+    if (check.type === 'dir') return s.isDirectory();
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Scan the project for installed AI/spec tools.
+ * Returns { detected: string[], available: string[] }
+ *   detected  — tool ids whose config files exist
+ *   available — all tool ids that could be selected
+ */
+export async function detectTools(projectRoot) {
+  const detected = [];
+
+  for (const tool of TOOL_REGISTRY) {
+    if (tool.detect.length === 0) continue;
+    for (const check of tool.detect) {
+      if (await checkDetect(projectRoot, check)) {
+        detected.push(tool.id);
+        break;
+      }
+    }
+  }
+
+  const available = TOOL_REGISTRY.map(t => t.id);
+  return { detected, available };
+}

package/src/adapters/handshake.js

@@ -0,0 +1,93 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { MARKER_START, MARKER_END, KNOWLEDGE_DIR } from '../constants.js';
+
+const SNIPPET = `${MARKER_START}
+## Project Knowledge
+
+This project maintains structured knowledge in \`${KNOWLEDGE_DIR}/\`:
+
+- **Principles** (\`${KNOWLEDGE_DIR}/principles.md\`): Core axioms and derived development principles — the project's non-negotiable rules.
+- **Vision** (\`${KNOWLEDGE_DIR}/vision.md\`): Goals, current state, architecture decisions, and roadmap.
+- **Experience** (\`${KNOWLEDGE_DIR}/experience.md\`): Distilled lessons from past development — patterns, pitfalls, and takeaways.
+
+Read these files at the start of any task to understand the project's *why* and constraints.
+Additional context may be found in \`${KNOWLEDGE_DIR}/research/\`, \`${KNOWLEDGE_DIR}/design/\`, and \`${KNOWLEDGE_DIR}/history/\`.
+${MARKER_END}`;
+
+const MDC_SNIPPET = `---
+description: Project knowledge context from Knowy
+globs:
+alwaysApply: true
+---
+
+${SNIPPET}`;
+
+function buildSnippet(format) {
+  if (format === 'mdc') return MDC_SNIPPET;
+  return SNIPPET;
+}
+
+/**
+ * Inject or update the Knowy reference in a tool's config file.
+ * Creates the file (and parent dirs) if it doesn't exist.
+ */
+export async function injectHandshake(projectRoot, target) {
+  const filePath = join(projectRoot, target.file);
+  const snippet = buildSnippet(target.format);
+
+  await mkdir(dirname(filePath), { recursive: true });
+
+  let content;
+  try {
+    content = await readFile(filePath, 'utf-8');
+  } catch {
+    // File doesn't exist — create with just the snippet
+    await writeFile(filePath, snippet + '\n');
+    return { action: 'created', file: target.file };
+  }
+
+  // Check if markers already exist
+  const startIdx = content.indexOf(MARKER_START);
+  const endIdx = content.indexOf(MARKER_END);
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Replace between markers (inclusive)
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + MARKER_END.length);
+    await writeFile(filePath, before + snippet + after);
+    return { action: 'updated', file: target.file };
+  }
+
+  // Append
+  const separator = content.endsWith('\n') ? '\n' : '\n\n';
+  await writeFile(filePath, content + separator + snippet + '\n');
+  return { action: 'appended', file: target.file };
+}
+
+/**
+ * Remove the Knowy reference from a file.
+ */
+export async function removeHandshake(projectRoot, target) {
+  const filePath = join(projectRoot, target.file);
+  let content;
+  try {
+    content = await readFile(filePath, 'utf-8');
+  } catch {
+    return { action: 'not_found', file: target.file };
+  }
+
+  const startIdx = content.indexOf(MARKER_START);
+  const endIdx = content.indexOf(MARKER_END);
+
+  if (startIdx === -1 || endIdx === -1) {
+    return { action: 'no_markers', file: target.file };
+  }
+
+  const before = content.slice(0, startIdx);
+  const after = content.slice(endIdx + MARKER_END.length);
+  // Clean up extra blank lines
+  const cleaned = (before + after).replace(/\n{3,}/g, '\n\n').trim();
+  await writeFile(filePath, cleaned ? cleaned + '\n' : '');
+  return { action: 'removed', file: target.file };
+}