@chrisdudek/yg 0.1.0

package/dist/templates/default-config.ts

@@ -0,0 +1,55 @@
+export const DEFAULT_CONFIG = `name: ""
+
+stack:
+  language: ""
+  runtime: ""
+
+standards: ""
+
+tags: []
+
+node_types:
+  - module
+  - service
+  - library
+
+artifacts:
+  responsibility.md:
+    required: always
+    description: "What this node is responsible for, and what it is not"
+  interface.md:
+    required:
+      when: has_incoming_relations
+    description: "Public API — methods, parameters, return types, contracts"
+    structural_context: true
+  constraints.md:
+    required: never
+    description: "Validation rules, business rules, invariants"
+  errors.md:
+    required:
+      when: has_incoming_relations
+    description: "Error conditions, codes, recovery behavior"
+    structural_context: true
+  state.md:
+    required: never
+    description: "State machines, lifecycle, transitions"
+  decisions.md:
+    required: never
+    description: "Local design decisions and rationale"
+
+knowledge_categories:
+  - name: decisions
+    description: "Global semantic decisions and their rationale"
+  - name: patterns
+    description: "Implementation conventions with examples"
+  - name: invariants
+    description: "System truths that must never be violated"
+
+quality:
+  min_artifact_length: 50
+  max_direct_relations: 10
+  context_budget:
+    warning: 5000
+    error: 10000
+  knowledge_staleness_days: 90
+`;

package/dist/templates/platform.ts

@@ -0,0 +1,257 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { AGENT_RULES_CONTENT } from './rules.js';
+
+const AGENT_RULES_IMPORT = '@.yggdrasil/agent-rules.md';
+const YGGDRASIL_START = '<!-- yggdrasil:start -->';
+const YGGDRASIL_END = '<!-- yggdrasil:end -->';
+const YGGDRASIL_SECTION = `## Yggdrasil\n\n${AGENT_RULES_CONTENT}`;
+const YGGDRASIL_BLOCK = `${YGGDRASIL_START}\n${YGGDRASIL_SECTION}\n${YGGDRASIL_END}`;
+
+export type Platform =
+  | 'cursor'
+  | 'claude-code'
+  | 'copilot'
+  | 'cline'
+  | 'roocode'
+  | 'codex'
+  | 'windsurf'
+  | 'aider'
+  | 'gemini'
+  | 'amp'
+  | 'generic';
+
+export const PLATFORMS: Platform[] = [
+  'cursor',
+  'claude-code',
+  'copilot',
+  'cline',
+  'roocode',
+  'codex',
+  'windsurf',
+  'aider',
+  'gemini',
+  'amp',
+  'generic',
+];
+
+export async function installRulesForPlatform(
+  projectRoot: string,
+  platform: Platform,
+): Promise<string> {
+  const agentRulesPath = path.join(projectRoot, '.yggdrasil', 'agent-rules.md');
+
+  switch (platform) {
+    case 'cursor':
+      return installForCursor(projectRoot);
+    case 'claude-code':
+      return installForClaudeCode(projectRoot, agentRulesPath);
+    case 'copilot':
+      return installForCopilot(projectRoot);
+    case 'cline':
+      return installForCline(projectRoot);
+    case 'roocode':
+      return installForRooCode(projectRoot);
+    case 'codex':
+      return installForCodex(projectRoot);
+    case 'windsurf':
+      return installForWindsurf(projectRoot);
+    case 'aider':
+      return installForAider(projectRoot, agentRulesPath);
+    case 'gemini':
+      return installForGemini(projectRoot, agentRulesPath);
+    case 'amp':
+      return installForAmp(projectRoot, agentRulesPath);
+    case 'generic':
+    default:
+      return installForGeneric(projectRoot);
+  }
+}
+
+async function ensureAgentRules(agentRulesPath: string): Promise<void> {
+  await mkdir(path.dirname(agentRulesPath), { recursive: true });
+  await writeFile(agentRulesPath, AGENT_RULES_CONTENT, 'utf-8');
+}
+
+async function installForCursor(projectRoot: string): Promise<string> {
+  const dir = path.join(projectRoot, '.cursor', 'rules');
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, 'yggdrasil.mdc');
+  const content = `---
+description: Yggdrasil — semantic memory of the repository
+alwaysApply: true
+---
+
+${AGENT_RULES_CONTENT}`;
+  await writeFile(filePath, content, 'utf-8');
+  return filePath;
+}
+
+async function installForClaudeCode(projectRoot: string, agentRulesPath: string): Promise<string> {
+  await ensureAgentRules(agentRulesPath);
+  const filePath = path.join(projectRoot, 'CLAUDE.md');
+  let existing = '';
+  try {
+    existing = await readFile(filePath, 'utf-8');
+  } catch {
+    /* file doesn't exist */
+  }
+  const importLine = AGENT_RULES_IMPORT;
+  if (existing.includes(importLine)) {
+    return agentRulesPath;
+  }
+  const content = existing.trimEnd() ? `${existing.trimEnd()}\n${importLine}\n` : `${importLine}\n`;
+  await writeFile(filePath, content, 'utf-8');
+  return agentRulesPath;
+}
+
+async function installForCopilot(projectRoot: string): Promise<string> {
+  const dir = path.join(projectRoot, '.github');
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, 'copilot-instructions.md');
+  let existing = '';
+  try {
+    existing = await readFile(filePath, 'utf-8');
+  } catch {
+    /* file doesn't exist */
+  }
+  let content: string;
+  if (existing.includes(YGGDRASIL_START) && existing.includes(YGGDRASIL_END)) {
+    content = existing.replace(
+      new RegExp(`${escapeRegex(YGGDRASIL_START)}[\\s\\S]*?${escapeRegex(YGGDRASIL_END)}`, 'g'),
+      YGGDRASIL_BLOCK,
+    );
+  } else {
+    content = existing.trimEnd()
+      ? `${existing.trimEnd()}\n\n${YGGDRASIL_BLOCK}\n`
+      : `${YGGDRASIL_BLOCK}\n`;
+  }
+  await writeFile(filePath, content, 'utf-8');
+  return filePath;
+}
+
+async function installForCline(projectRoot: string): Promise<string> {
+  const dir = path.join(projectRoot, '.clinerules');
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, 'yggdrasil.md');
+  await writeFile(filePath, AGENT_RULES_CONTENT, 'utf-8');
+  return filePath;
+}
+
+async function installForRooCode(projectRoot: string): Promise<string> {
+  const dir = path.join(projectRoot, '.roo', 'rules');
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, 'yggdrasil.md');
+  await writeFile(filePath, AGENT_RULES_CONTENT, 'utf-8');
+  return filePath;
+}
+
+async function installForCodex(projectRoot: string): Promise<string> {
+  const filePath = path.join(projectRoot, 'AGENTS.md');
+  let existing = '';
+  try {
+    existing = await readFile(filePath, 'utf-8');
+  } catch {
+    /* file doesn't exist */
+  }
+  let content: string;
+  if (existing.includes(YGGDRASIL_START) && existing.includes(YGGDRASIL_END)) {
+    content = existing.replace(
+      new RegExp(`${escapeRegex(YGGDRASIL_START)}[\\s\\S]*?${escapeRegex(YGGDRASIL_END)}`, 'g'),
+      YGGDRASIL_BLOCK,
+    );
+  } else {
+    content = existing.trimEnd()
+      ? `${existing.trimEnd()}\n\n${YGGDRASIL_BLOCK}\n`
+      : `${YGGDRASIL_BLOCK}\n`;
+  }
+  await writeFile(filePath, content, 'utf-8');
+  return filePath;
+}
+
+async function installForWindsurf(projectRoot: string): Promise<string> {
+  const dir = path.join(projectRoot, '.windsurf', 'rules');
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, 'yggdrasil.md');
+  await writeFile(filePath, AGENT_RULES_CONTENT, 'utf-8');
+  return filePath;
+}
+
+async function installForAider(projectRoot: string, agentRulesPath: string): Promise<string> {
+  await ensureAgentRules(agentRulesPath);
+  const filePath = path.join(projectRoot, '.aider.conf.yml');
+  const entry = '.yggdrasil/agent-rules.md';
+  let existing = '';
+  try {
+    existing = await readFile(filePath, 'utf-8');
+  } catch {
+    /* file doesn't exist */
+  }
+  if (existing.includes(entry)) {
+    return agentRulesPath;
+  }
+  const content = appendAiderReadEntry(existing, entry);
+  await writeFile(filePath, content, 'utf-8');
+  return agentRulesPath;
+}
+
+function appendAiderReadEntry(existing: string, entry: string): string {
+  const newItem = `  - ${entry}  # added by yg init\n`;
+  const readBlock = /^read:\s*\n((?:\s+-\s+[^\n]+\n)*)/m;
+  const match = existing.match(readBlock);
+  if (match) {
+    return existing.replace(match[0], `read:\n${match[1]}${newItem}`);
+  }
+  const readEmpty = /^read:\s*$/m;
+  if (readEmpty.test(existing)) {
+    return existing.replace(readEmpty, `read:\n${newItem}`);
+  }
+  const trimmed = existing.trimEnd();
+  return trimmed ? `${trimmed}\n\nread:\n${newItem}` : `read:\n${newItem}`;
+}
+
+async function installForGemini(projectRoot: string, agentRulesPath: string): Promise<string> {
+  await ensureAgentRules(agentRulesPath);
+  const filePath = path.join(projectRoot, 'GEMINI.md');
+  let existing = '';
+  try {
+    existing = await readFile(filePath, 'utf-8');
+  } catch {
+    /* file doesn't exist */
+  }
+  const importLine = AGENT_RULES_IMPORT;
+  if (existing.includes(importLine)) {
+    return agentRulesPath;
+  }
+  const content = existing.trimEnd() ? `${existing.trimEnd()}\n${importLine}\n` : `${importLine}\n`;
+  await writeFile(filePath, content, 'utf-8');
+  return agentRulesPath;
+}
+
+async function installForAmp(projectRoot: string, agentRulesPath: string): Promise<string> {
+  await ensureAgentRules(agentRulesPath);
+  const filePath = path.join(projectRoot, 'AGENTS.md');
+  let existing = '';
+  try {
+    existing = await readFile(filePath, 'utf-8');
+  } catch {
+    /* file doesn't exist */
+  }
+  const importLine = AGENT_RULES_IMPORT;
+  if (existing.includes(importLine)) {
+    return agentRulesPath;
+  }
+  const content = existing.trimEnd() ? `${existing.trimEnd()}\n${importLine}\n` : `${importLine}\n`;
+  await writeFile(filePath, content, 'utf-8');
+  return agentRulesPath;
+}
+
+async function installForGeneric(projectRoot: string): Promise<string> {
+  const filePath = path.join(projectRoot, '.yggdrasil', 'agent-rules.md');
+  await ensureAgentRules(filePath);
+  return filePath;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/templates/rules.ts

@@ -0,0 +1,142 @@
+/**
+ * Canonical agent rules content — hand-tuned, do not generate programmatically.
+ *
+ * Operating manual for agents: graph-first, exhaustive coverage, context is sufficient.
+ */
+export const AGENT_RULES_CONTENT = `# Yggdrasil - System Semantic Memory (Operating Manual)
+
+You are working in a repository managed by Yggdrasil.
+Yggdrasil is a persistent, structured semantic memory graph stored in \`.yggdrasil/\`. It maps the repository, dictates system rules, and assembles implementation contexts.
+
+THIS PROMPT IS YOUR ENTIRE OPERATING MANUAL. Read it carefully. Follow it strictly.
+
+---
+
+## 1. CORE PRINCIPLES (NON-NEGOTIABLE)
+
+1. **Graph First, Always:** Before answering a question, modifying code, or planning a feature, you MUST consult the graph.
+2. **Context is Sufficient:** If you feel the need to randomly explore source files to understand what a node should do, the graph is incomplete. **Fix the graph** (add decisions, interface details, constraints). Do not bypass the graph by reading raw code.
+3. **Graph is Intended Truth:** If the code and graph diverge, the graph is the truth. If a code change is deliberate, update the graph to match.
+4. **Exhaustive Coverage:** Every source file MUST belong to exactly one graph node. No orphaned files.
+5. **Tools Read, You Write:** The \`yg\` CLI tools only read, validate, and manage metadata. YOU must create and edit graph directories, \`.yaml\` files, and \`.md\` artifacts manually.
+6. **English Only for Artifacts:** All graph artifact files (filenames from \`config.artifacts\`, in the same directory as \`node.yaml\`) MUST be written in English. Conversation can be in the user's language.
+7. **Never Touch Operational Metadata:** NEVER manually edit \`.yggdrasil/.drift-state\` or \`.yggdrasil/.journal.yaml\`.
+
+---
+
+## 2. CONVERSATION LIFECYCLE (YOUR HABITS)
+
+You do not need explicit "session" commands. Follow these conversational triggers:
+
+### A. Preflight (First message of the conversation)
+Always execute these commands before doing anything else:
+1. \`yg journal-read\` -> If entries exist, consolidate them into the graph, then \`yg journal-archive\`.
+2. \`yg drift\` -> If divergence is detected, present states (\`ok\`, \`drift\`, \`missing\`, \`unmaterialized\`). Ask the user: Absorb (update graph) or Reject (re-materialize code from graph)?
+3. \`yg status\` -> Report graph health.
+4. \`yg validate\` -> If W008 stale-knowledge appears, update the knowledge artifacts to reflect current node state.
+
+### B. Wrap-up (User signals closing the topic)
+Triggered by phrases like: "kończymy", "wrap up", "to tyle", "gotowe".
+**Note: The graph should ALREADY be up to date. Do not wait for wrap-up to update graph artifacts.**
+1. If iterative journal mode was used: consolidate notes to the graph, then \`yg journal-archive\`.
+2. \`yg drift\` -> Check if files changed manually during the conversation.
+3. \`yg validate\` -> Fix any structural errors.
+4. Report exactly what nodes and files were changed.
+
+---
+
+## 3. WORKFLOW: MODIFYING OR CREATING FILES
+
+You are NOT ALLOWED to edit or create source code without establishing graph coverage first.
+
+**Step 1: Check coverage** -> Run \`yg owner --file <path>\`
+
+**Step 2: If Owner FOUND (The Execution Checklist)**
+Whenever you write or edit source code, you MUST output this exact checklist in your response to the user, and execute each step BEFORE finishing your turn. This forces you to remember the graph:
+
+- [x] 1. Read Specification (ran \`yg build-context\`)
+- [x] 2. Modify Source Code
+- [x] 3. Sync Graph Artifacts (manually edit the node's artifact files — filenames from \`config.artifacts\` — IMMEDIATELY to match new code behavior)
+- [x] 4. Baseline Hash (ran \`yg drift-sync\` ONLY AFTER updating the graph)
+
+*If you do not print this checklist and check off step 3, you have failed the core directive of Yggdrasil.*
+
+**Step 3: If Owner NOT FOUND (Uncovered Area)**
+STOP. Do not modify the code. First determine: **Is this greenfield (empty or new code to be created)?**
+
+*   **If GREENFIELD (empty directory, new project, code not yet written):** Do NOT offer blackbox. Use Option 1 only — create proper nodes (reverse engineering or upfront design) before implementing. Blackbox is forbidden for new code.
+*   **If EXISTING CODE (legacy, third-party, shipped-but-unmapped):** Present the user with 3 options and wait for their decision:
+    *   **Option 1: Reverse Engineering:** Create/extend standard nodes to map the area fully before modifying.
+    *   **Option 2: Blackbox Coverage:** Create a \`blackbox: true\` node at a user-chosen granularity to establish ownership without deep semantic exploration.
+    *   **Option 3: Abort/Change Plan:** Do not touch the file.
+
+
+---
+
+## 4. WORKFLOW: MODIFYING THE GRAPH & BLAST RADIUS
+
+When adding features or changing architecture, update the graph FIRST.
+
+**DO NOT DEFER GRAPH UPDATES:**
+*   **DO NOT wait for the user to confirm if a change is "final".** The graph must evolve continuously with your code edits.
+*   **Default Behavior:** If iterative journal mode is OFF, you MUST write structural and semantic changes directly to the graph files (\`node.yaml\`, artifacts or other files like aspects or flows, etc.) IMMEDIATELY. Suppress your innate safety bias to wait for permission.
+
+1. **Check Blast Radius:** Before modifying a node that others depend on, run \`yg impact --node <node_path> --simulate\`. Report the impact to the user.
+2. **Read Config & Templates:**
+    *   Check \`.yggdrasil/config.yaml\` for allowed \`node_types\` and \`tags\`.
+    *   **CRITICAL:** ALWAYS read the required schema files in \`.yggdrasil/templates/\` (e.g., \`node.yaml\`, \`service.yaml\`) to know the exact fields and structure before creating or editing any graph file.
+3. **Validate & Fix:** Run \`yg validate\`. You must fix all E-codes (Errors).
+4. **Token Economy & W-codes (Warnings):**
+    *   If you see \`W005 budget-warning\` or \`W006 budget-error\`, the context package is too large. You MUST consider splitting the node or reducing dependencies.
+    *   If you see \`W008 stale-knowledge\`, the semantic memory is outdated compared to the code. Update the knowledge artifacts.
+    *   **Smallest Viable Scope:** Prefer \`scope: nodes\` over \`scope: tags\`. Prefer tags over \`scope: global\`. Global scope costs token budget in EVERY context package.
+
+**Journaling (Iterative Mode):**
+*   **Default:** Write changes directly to graph files immediately.
+*   **Opt-in:** ONLY if the user says "tryb iteracyjny" or "użyj journala", use \`yg journal-add --note "..."\` to buffer intent during fast ping-pong changes.
+
+---
+
+## 5. PATH CONVENTIONS (CRITICAL)
+
+To avoid broken references (\`E004\`, \`E005\`), use correct relative paths:
+*   **Node paths** (used in CLI, relations, flow nodes): Relative to \`.yggdrasil/model/\` (e.g., \`orders/order-service\`).
+*   **File paths** (used in mapping, \`yg owner\`): Relative to the repository root (e.g., \`src/modules/orders/order.service.ts\`).
+*   **Knowledge paths** (used in node explicit refs): Relative to \`.yggdrasil/knowledge/\` (e.g., \`decisions/001-event-sourcing\`).
+
+---
+
+## 6. GRAPH STRUCTURE, CONFIG & TEMPLATES CHEAT SHEET
+
+The graph lives entirely under \`.yggdrasil/\`. You NEVER guess structure. You MUST ALWAYS read the corresponding schema reference in \`.yggdrasil/templates/\` before creating or editing any graph file.
+
+*   **\`.yggdrasil/config.yaml\`**: The ONLY config file. Defines \`node_types\`, \`tags\`, \`artifacts\`, \`knowledge_categories\`, and quality thresholds. Read this before any graph work.
+*   **\`.yggdrasil/templates/\`**: The SINGLE place for all templates and schemas.
+    *   Contains node-type templates (e.g., \`service.yaml\`, \`module.yaml\`) with suggested artifacts and guidance.
+    *   Contains schema references (\`node.yaml\`, \`aspect.yaml\`, \`flow.yaml\`, \`knowledge.yaml\`) showing exact file structures.
+*   **\`.yggdrasil/model/\`**: Node tree. Each node is a directory with \`node.yaml\` and artifact files (filenames from \`config.artifacts\`; required ones depend on config).
+*   **\`.yggdrasil/aspects/\`**: Cross-cutting rules. Directory contains \`aspect.yaml\` (binds via \`tag: <name>\`) and \`.md\` content.
+*   **\`.yggdrasil/flows/\`**: End-to-end processes. Directory contains \`flow.yaml\` (lists \`nodes: [paths]\` and \`knowledge: [paths]\`) and \`.md\` content.
+*   **\`.yggdrasil/knowledge/\`**: Repo-wide wisdom (\`decisions/\`, \`patterns/\`, \`invariants/\`). Directory contains \`knowledge.yaml\` and \`.md\` content.
+
+---
+
+## 7. CLI TOOLS REFERENCE (\`yg\`)
+
+Always use these exact commands.
+
+*   \`yg owner --file <file_path>\` -> Find owning node.
+*   \`yg build-context --node <node_path>\` -> Assemble strict specification.
+*   \`yg tree [--root <node_path>] [--depth N]\` -> Print graph structure.
+*   \`yg deps --node <node_path> [--type structural|event|all]\` -> Show dependencies.
+*   \`yg impact --node <node_path> --simulate\` -> Simulate blast radius.
+*   \`yg status\` -> Graph health metrics.
+*   \`yg validate [--scope <node_path>|all]\` -> Compile/check graph. Run after EVERY graph edit.
+*   \`yg drift [--scope <node_path>|all]\` -> Check code vs graph baseline.
+*   \`yg drift-sync --node <node_path>\` -> Save current file hash as new baseline. Run ONLY after ensuring graph artifacts match the code.
+
+*(Iterative mode only)*
+*   \`yg journal-read\`
+*   \`yg journal-add --note "<content>" [--target <node_path>]\`
+*   \`yg journal-archive\`
+`;

package/graph-templates/aspect.yaml

@@ -0,0 +1,2 @@
+name: CrossCuttingRequirementName
+tag: requires-tag-from-config

package/graph-templates/flow.yaml

@@ -0,0 +1,8 @@
+name: EndToEndProcessName
+nodes:
+  - orders/order-service
+  - payments/payment-service
+  - inventory/inventory-service
+knowledge:
+  - patterns/saga-pattern
+  - decisions/001-event-sourcing

package/graph-templates/knowledge-scope-nodes.yaml

@@ -0,0 +1,5 @@
+name: DecisionOrPatternName
+scope:
+  nodes:
+    - orders/order-service
+    - users/user-repository

package/graph-templates/knowledge-scope-tags.yaml

@@ -0,0 +1,3 @@
+name: PatternOrDecisionName
+scope:
+  tags: [service, controller]

package/graph-templates/knowledge.yaml

@@ -0,0 +1,2 @@
+name: ArchitecturalDecisionOrPatternName
+scope: global

package/graph-templates/library.yaml

@@ -0,0 +1,22 @@
+node_type: library
+suggested_artifacts:
+  - responsibility
+  - interface
+guidance: |
+  A library node represents shared code, utilities, or reusable components that
+  other nodes depend on. It has no business logic of its own — it provides
+  capabilities.
+
+  responsibility.md: Define what capabilities this library provides and what it
+  does not. "Provides date formatting, timezone conversion, and scheduling helpers.
+  Does not contain business rules or domain logic."
+
+  interface.md: Required when other nodes depend on this one. List exported functions,
+  classes, or APIs. For each: signature, purpose, usage constraints. Libraries are
+  often consumed by many nodes — a clear interface prevents misuse.
+
+  constraints.md: Optional. Use for usage constraints: "All dates must be ISO 8601
+  UTC. Thread-safe. No side effects."
+
+  mapping: Typically "directory" pointing to the library source. Path relative
+  to repository root.

package/graph-templates/module.yaml

@@ -0,0 +1,18 @@
+node_type: module
+suggested_artifacts:
+  - responsibility
+guidance: |
+  A module node represents a domain or subsystem that groups child components.
+  It provides domain context that all descendants inherit during context assembly.
+
+  responsibility.md: Define the business domain this module owns. What is in scope
+  (e.g. "orders, order lifecycle, order state transitions") and what is out of scope
+  (e.g. "payment processing belongs to payments module"). Child nodes inherit this
+  context — a service under this module is understood within this domain.
+
+  Modules typically have no mapping (they are organizational, not implementation units).
+  If the module maps to a directory, that directory contains the implementation of
+  all child nodes collectively.
+
+  Keep responsibility concise but precise. The agent uses it to understand boundaries
+  when implementing or modifying child nodes.

package/graph-templates/node.yaml

@@ -0,0 +1,17 @@
+name: ComponentName
+type: service
+tags: []
+blackbox: false
+
+relations:
+  - target: other/module-path
+    type: calls
+    consumes: [methodA, methodB]
+    failure: 'retry 3x, then circuit-break'
+
+knowledge:
+  - decisions/001-choice-name
+
+mapping:
+  paths:
+    - src/modules/component/

package/graph-templates/service.yaml

@@ -0,0 +1,30 @@
+node_type: service
+suggested_artifacts:
+  - responsibility
+  - interface
+  - constraints
+  - errors
+guidance: |
+  A service node represents a component with a public API that other components depend on.
+  It is the primary implementation unit for business logic.
+
+  responsibility.md: State clearly what this service does and what it does NOT do.
+  Define boundaries: "Creates and validates orders; does not process payments."
+  Include edge cases: "Handles partial fulfillment; does not handle refunds."
+
+  interface.md: Required when other nodes depend on this one (has_incoming_relations).
+  List every public method with: name, parameters (types), return type, contract.
+  For each method: preconditions, postconditions, idempotency, error conditions.
+  Example: "createOrder(items: OrderItem[]): Promise<Order> — creates order in pending
+  state; items must have positive quantity; returns order with generated id."
+
+  constraints.md: Validation rules, business rules, invariants this service enforces.
+  Be explicit: "Order must have at least 1 item, max 100 items. Total must be > 0."
+  Include rate limits, quotas, or SLA constraints if applicable.
+
+  errors.md: Required when others depend on this node. Document error conditions,
+  error codes, and recovery behavior. "INSUFFICIENT_STOCK: retry after inventory
+  refresh. PAYMENT_FAILED: order marked payment-failed, manual intervention."
+
+  mapping: Use type "directory" for a service implemented in one folder, or "file"
+  for a single-file service. Path relative to repository root.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@chrisdudek/yg",
+  "version": "0.1.0",
+  "description": "Make your repository self-aware. Persistent semantic memory and deterministic context assembly for AI agents.",
+  "type": "module",
+  "bin": {
+    "yg": "./dist/bin.js"
+  },
+  "files": [
+    "dist/",
+    "graph-templates/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "yggdrasil",
+    "graph",
+    "ai",
+    "specification",
+    "architecture",
+    "cli",
+    "agent-commands",
+    "code-generation"
+  ],
+  "author": "Krzysztof Dudek <me@chrisdudek.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/krzysztofdudek/Yggdrasil#readme",
+  "bugs": {
+    "url": "https://github.com/krzysztofdudek/Yggdrasil/issues",
+    "email": "me@chrisdudek.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/krzysztofdudek/Yggdrasil.git",
+    "directory": "source/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "ignore": "^7.0.5",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.1",
+    "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^4.0.18"
+  }
+}