dotdog 0.2.5 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.3.1
+
+- Fix npm packaging: homepage, bugs, engines, repository fields
+- Trim keywords to 8 specific terms
+- Ship correct README, LICENSE, and CHANGELOG in package
+- CLI help text uses colons, no em dashes
+
+## 0.3.0
+
+- `dotdog analyze` — deep project analysis: score, gaps, entity audit
+- `dotdog generate` — generate missing spec files from SPEC.dog
+- `dotdog simulate` — run simulation scenarios
+- `.dag` v1.2: provable token savings, typed nodes and edges
+- VS Code extension: syntax highlighting for .dog files
+- GitHub Pages and llms.txt for AI agent discoverability
+- `dotdog serve` MCP server: getEntity, traverse, search, schema, summary
+- Path traversal guard, traverse depth cap, serve hardening
+
+## 0.2.0
+
+- `dotdog compile` — compile .dog files to .dag graph
+- `dotdog visualize` — Mermaid graph output with --save flag
+- MCP server: expose .dag graph to AI agents over stdio
+- `dotdog staleness` — detect drift between spec and reality
+- `dotdog init` — scaffold new spec genome projects
+- `dotdog list` — list all projects and .dog file counts
+
+## 0.1.0
+
+- `.dog` file format v1.0
+- `.dag` file format v1.0
+- `dotdog validate` — validate spec completeness
+- `dotdog parse` — parse .dog files

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 specdog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,76 +1,130 @@
-# spec-platform
+# dotdog
 
-Monorepo for the Spec Platform — a knowledge graph system where specs ARE the database and LLMs ARE the query engine.
+[![npm version](https://img.shields.io/npm/v/dotdog)](https://www.npmjs.com/package/dotdog)
+[![npm downloads](https://img.shields.io/npm/dm/dotdog)](https://www.npmjs.com/package/dotdog)
+[![License: MIT](https://img.shields.io/npm/l/dotdog)](https://github.com/specdog/dotdog/blob/main/LICENSE)
+[![CI](https://github.com/specdog/dotdog/actions/workflows/test.yml/badge.svg)](https://github.com/specdog/dotdog/actions)
 
-## The Flywheel
+> **Feed the dog. Ship with specs.** Write .dog specs. Dog checks them. AI agents fetch them.
 
-```
-spec → validate → app → data → better spec → better app → ...
+## Install
+
+```bash
+npm install -g dotdog
 ```
 
-The spec describes the platform. The platform validates the spec. The validation report improves the spec. Each cycle adds granularity.
+Requires Node.js >= 20.
 
-## Structure
+## Quick Start
 
+```bash
+dotdog init my-project     # scaffold a spec genome
+dotdog validate            # score completeness (0-100%)
+dotdog analyze             # deep analysis : gaps, suggestions, entity audit
 ```
-spec-platform/
-├── packages/
-│   ├── spec-engine/     # Core types and ontology (shared by everything)
-│   ├── spec-mcp/        # MCP Server — AI agents query specs via stdio
-│   └── spec-cli/        # CLI — spec validate, init, simulate, list
-├── projects/            # Spec genomes (dogfooding)
-│   └── spec-platform/
-│       └── specs/
-│           ├── SPEC.dog          # Product spec — screens, flows, stories
-│           ├── constitution.dog  # Immutable rules
-│           └── data-model.dog    # Graph ontology — nodes, edges, tasks, predictions, vectors
-├── templates/           # Spec genome templates for new projects
-└── package.json         # Bun workspace root
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `dotdog validate [dir]` | Score spec completeness. Checks file existence, entity descriptions, section counts. |
+| `dotdog analyze [dir]` | Deep analysis. Detects domain, stack, gaps with severity, entity quality audit. |
+| `dotdog parse <file>` | Parse a `.dog` file into sections. |
+| `dotdog compile [dir]` | Compile `.dog` files into a `.dag` graph (JSON). |
+| `dotdog visualize [dir]` | Output Mermaid graph from `.dag`. `--save` writes `.md` for GitHub rendering. |
+| `dotdog serve [dir]` | Start MCP server over stdio. AI agents query specs without hallucination. |
+| `dotdog staleness [dir]` | Detect drift between spec and reality. Compares plan.dog tasks against code. |
+| `dotdog generate [dir]` | Generate missing spec files from SPEC.dog (data-model, COPY, INDEX). |
+| `dotdog simulate <scenario>` | Run a simulation scenario. Reads SPEC.dog scenarios, checks pre/postconditions. |
+| `dotdog init <project>` | Scaffold a new spec genome project with templates. |
+| `dotdog list` | List all projects and their `.dog` file counts. |
+
+## File Formats
+
+### `.dog` : Human-Written Spec Genome
+
+Markdown prose + YAML structured blocks. Free and open source. Define entities, relationships, events, predictions, and copy in a single format that both humans and parsers understand.
+
+```markdown
+### Entity: User
+
+A person who uses the app.
+
+` ``yaml
+entity: User
+type: entity
+properties:
+  id:
+    type: string
+    required: true
+  email:
+    type: string
+    required: true
+states: [active, suspended]
+lifecycle: active → suspended
+` ``
 ```
 
-## Quick Start
+### `.dag` : Machine-Compiled Graph
 
-```bash
-bun install
-cd projects/spec-platform/specs
+JSON graph compiled from `.dog` files. Nodes, edges, properties, and states in a deterministic structure. 85% token savings vs raw `.dog` files for AI agents.
 
-# Validate our own spec (dogfood)
-bun ../../../packages/spec-cli/src/index.ts validate ../..
+## MCP Server : AI Agent Integration
 
-# List projects
-bun ../../../packages/spec-cli/src/index.ts list
-```
+`dotdog serve` exposes specs to any MCP-compatible AI agent over stdio. Six tools:
 
-## $0 Stack
+| Tool | Description |
+|------|-------------|
+| `getEntity` | Exact entity with properties, states, lifecycle, and connected edges |
+| `traverse` | BFS subgraph from any starting node to any depth |
+| `search` | Find entities by name or type |
+| `schema` | Property definitions only : zero prose, agent-optimized |
+| `summary` | Node count, edge count, file count, compile time |
+| `listProjects` | Array of project names |
 
-| Component | Technology | Cost |
-|-----------|-----------|------|
-| Runtime | Bun | $0 |
-| Database | bun:sqlite (embedded) | $0 |
-| Types | TypeScript (strict) | $0 |
-| CLI | Commander.js + chalk | $0 |
-| MCP Server | @modelcontextprotocol/sdk (stdio) | $0 |
-| Embeddings | all-MiniLM-L6-v2 (local) | $0 |
-| Hosting | None needed (local-first) | $0 |
+Agent workflow: `listProjects` → `getEntity` → `traverse` graph.
 
-## The Spec Graph
+## Dogfood
 
-The spec is not a document. It's a knowledge graph.
+dotdog validates its own specs. Every PR:
+
+```
+dotdog validate → find gaps → fix spec → PR → merge → tag → CI publish
+```
 
-- **Nodes**: entities, tasks, predictions, screens, constraints, user stories
-- **Edges**: contains, depends_on, implements, references, calls, precedes
-- **Vectors**: every section embedded for semantic search, contradiction detection, staleness checks
-- **Predictions**: forecasts with triggers, timeframes, confidence, and actual outcome tracking
+Eat your own dogfood. The tool is the project.
 
-LLMs traverse the graph at query time. They don't read prose and guess — they get exact typed values.
+## VS Code Extension
 
-## Score
+Syntax highlighting for `.dog` files. Install:
 
+```bash
+cp -r extensions/vscode ~/.vscode/extensions/dotdog
 ```
-spec validate → 43% complete
 
-  ✓ SPEC.dog
-  ✓ constitution.dog
-  ✓ data-model.dog
-  ⚠ COPY.dog, DESIGN-SYSTEM.dog, plan.dog, INDEX.dog
+## Format Specifications
+
+- [`.dog` format spec](spec/format-spec.dog) : language definition, EBNF grammar, validation rules
+- [`.dag` format spec](spec/format-spec-dag.dog) : graph definition, MCP API, token efficiency
+
+## Links
+
+- **GitHub:** [specdog/dotdog](https://github.com/specdog/dotdog)
+- **npm:** [dotdog](https://www.npmjs.com/package/dotdog)
+- **Docs:** [GitHub Pages](https://specdog.github.io/dotdog)
+- **llms.txt:** [llms.txt](llms.txt) : structured for AI agent discovery
+- **AGENTS.md:** [AGENTS.md](AGENTS.md) : instructions for AI coding agents
+
+## Spec-Driven Development
+
+dotdog is built for SDD. Write your spec first. Validate it. Compile it. Let AI agents query it. The spec is the source of truth.
+
+```
+spec → validate → compile → serve → AI agent queries
 ```
+
+No more specs that rot in a wiki. No more agents guessing from prose. One source. Zero ambiguity.
+
+## License
+
+MIT

package/dist/cli.js

@@ -2535,8 +2535,9 @@ var source_default = chalk;
 
 // src/cli.ts
 import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, mkdirSync, writeFileSync } from "fs";
-import { join as join2 } from "path";
+import { join as join2, resolve as resolve2 } from "path";
 import { homedir as homedir2 } from "os";
+import { createHash } from "crypto";
 
 // src/parser.ts
 function parse(source) {
@@ -2896,13 +2897,21 @@ function parseInlineObject(value) {
 }
 // src/serve.ts
 import { existsSync, readdirSync, readFileSync } from "fs";
-import { join } from "path";
+import { join, resolve } from "path";
 import { homedir } from "os";
 import * as readline from "readline";
 function resolvePath(p) {
   if (p.startsWith("~"))
     p = join(homedir(), p.slice(1));
-  return p.startsWith("/") ? p : join(process.cwd(), p);
+  const resolved = p.startsWith("/") ? p : join(process.cwd(), p);
+  if (!p.startsWith("/") && !p.startsWith("~")) {
+    const rel = resolve(process.cwd(), p);
+    if (!rel.startsWith(process.cwd() + "/") && rel !== process.cwd()) {
+      throw new Error(`Path traversal blocked: ${p}`);
+    }
+    return rel;
+  }
+  return resolved;
 }
 function serve(dir = ".") {
   const root = resolvePath(dir);
@@ -2977,7 +2986,7 @@ function serve(dir = ".") {
         const dag = dagCache.get(args.project || [...dagCache.keys()][0] || "");
         if (!dag)
           return { jsonrpc: "2.0", id, error: { code: 404, message: "Project not found" } };
-        const depth = args.depth || 1;
+        const depth = Math.min(Math.max(1, args.depth || 1), 20);
         const visited = new Set;
         const subgraph = { nodes: [], edges: [] };
         const queue = [{ id: args.from, depth: 0 }];
@@ -3059,7 +3068,15 @@ function serve(dir = ".") {
 function resolvePath2(p) {
   if (p.startsWith("~"))
     p = join2(homedir2(), p.slice(1));
-  return p.startsWith("/") ? p : join2(process.cwd(), p);
+  const resolved = p.startsWith("/") ? p : join2(process.cwd(), p);
+  if (!p.startsWith("/") && !p.startsWith("~")) {
+    const rel = resolve2(process.cwd(), p);
+    if (!rel.startsWith(process.cwd() + "/") && rel !== process.cwd()) {
+      throw new Error(`Path traversal blocked: ${p}`);
+    }
+    return rel;
+  }
+  return resolved;
 }
 function parseSections2(markdown) {
   const lines = markdown.split(`
@@ -3094,9 +3111,10 @@ function parseSections2(markdown) {
 }
 var program2 = new Command;
 var pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf-8"));
-program2.name("spec").alias("dotdog").description("The spec dog — validate, analyze, generate .dog files").version(pkg.version);
+program2.name("spec").alias("dotdog").description("CLI for structured software specs : validate .dog, compile .dag, query via MCP").version(pkg.version);
 program2.command("validate [dir]").action((d = ".") => {
-  const dirs = [join2(d, "projects"), join2(d, "specs")];
+  const dir = resolvePath2(d);
+  const dirs = [join2(dir, "projects"), join2(dir, "specs")];
   let found = false;
   for (const dd of dirs) {
     if (!existsSync2(dd))
@@ -3109,7 +3127,7 @@ program2.command("validate [dir]").action((d = ".") => {
       const missing = ["SPEC.dog", "constitution.dog", "data-model.dog"].filter((f) => !files.includes(f));
       const optional = ["COPY.dog", "plan.dog", "DESIGN-SYSTEM.dog", "INDEX.dog"].filter((f) => !files.includes(f));
       console.log(source_default.bold(`
-  ${p} — ${files.length} .dog files, ${100 - Math.round((missing.length * 3 + optional.length) / 20 * 100)}% complete`));
+  ${p} : ${files.length} .dog files, ${100 - Math.round((missing.length * 3 + optional.length) / 20 * 100)}% complete`));
       for (const f of files)
         console.log(source_default.gray(`    ${f}`));
       if (missing.length)
@@ -3176,7 +3194,7 @@ ${d}/`));
     for (const p of projects) {
       const sp = join2(dd, p, "specs");
       const n = existsSync2(sp) ? readdirSync2(sp).filter((f) => f.endsWith(".dog")).length : 0;
-      console.log(`  ${source_default.cyan(p)} — ${n} .dog files`);
+      console.log(`  ${source_default.cyan(p)} : ${n} .dog files`);
     }
   }
 });
@@ -3200,45 +3218,64 @@ program2.command("compile [dir]").option("-o, --output <file>").action((d = ".",
       const pd = join2(dd, p, "specs");
       if (!existsSync2(pd))
         continue;
-      const files = readdirSync2(pd).filter((f) => f.endsWith(".dog"));
-      const dag = { version: "1.1", project: p, compiled_at: new Date().toISOString(), nodes: [], edges: [], files: files.length };
+      const files = readdirSync2(pd).filter((f) => f.endsWith(".dog")).sort();
+      if (!files.length)
+        continue;
+      found = true;
+      const sources = {};
+      let sourceBytes = 0;
+      const hash = createHash("sha256");
       for (const f of files) {
         const content = readFileSync2(join2(pd, f), "utf-8");
-        const ast = parse(content);
+        sources[f] = content;
+        sourceBytes += Buffer.byteLength(content, "utf-8");
+        hash.update(content);
+        hash.update(`
+`);
+      }
+      const integrity = { sha256: hash.digest("hex"), source_files: files.length, source_bytes: sourceBytes };
+      const sourceTokens = Math.round(sourceBytes / 4);
+      const nodes = [], edges = [];
+      for (const f of files) {
+        const ast = parse(sources[f]);
         for (const section of ast.sections) {
           for (const block of section.blocks) {
             if (block.kind === "entity") {
-              dag.nodes.push({
+              nodes.push({
                 id: block.name,
                 type: block.type,
                 description: block.description || "",
                 file: f,
-                properties: block.properties,
+                properties: Object.keys(block.properties).length,
                 states: block.states || [],
-                lifecycle: block.lifecycle || [],
                 chars: section.content?.length || 0
               });
             }
             if (block.kind === "relationship") {
-              dag.edges.push({
+              edges.push({
                 source: block.source,
                 target: block.target,
                 verb: block.verb,
                 cardinality: block.cardinality,
                 required: block.required,
-                cascade: block.cascade,
-                file: f,
-                section: section.heading
+                file: f
               });
             }
           }
         }
       }
-      found = true;
-      const out = opts.output || join2(pd, "..", `${p}.dag`);
-      writeFileSync(out, JSON.stringify(dag, null, 2));
-      console.log(source_default.green(`  ✓ ${out}`));
-      console.log(source_default.gray(`    ${dag.nodes.length} nodes, ${dag.edges.length} edges, ${dag.files} files`));
+      const dag = { version: "1.2", project: p, compiled_at: new Date().toISOString(), compiler: `dotdog@${pkg.version}`, integrity, nodes, edges };
+      const dagJson = JSON.stringify(dag);
+      const dagTokens = Math.round(Buffer.byteLength(dagJson, "utf-8") / 4);
+      const savingsPct = sourceTokens > 0 ? Math.round((1 - dagTokens / sourceTokens) * 1000) / 10 : 0;
+      const savingsTokens = sourceTokens - dagTokens;
+      const outPath = opts.output || join2(pd, "..", `${p}.dag`);
+      const report = { ...dag, tokens: { source_total: sourceTokens, dag_total: dagTokens, savings_pct: savingsPct, savings_tokens: savingsTokens } };
+      writeFileSync(outPath, JSON.stringify(report, null, 2));
+      console.log(source_default.green(`  ✓ ${outPath}`));
+      console.log(source_default.gray(`    ${nodes.length} nodes, ${edges.length} edges, ${files.length} files`));
+      console.log(source_default.gray(`    ${sourceTokens} → ${dagTokens} tokens (${savingsPct}% savings, ${savingsTokens} tokens saved)`));
+      console.log(source_default.gray(`    sha256: ${integrity.sha256.substring(0, 12)}...`));
     }
   }
   if (!found)
@@ -3266,7 +3303,7 @@ program2.command("visualize [dir]").option("-s, --save").action((d = ".", opts)
       out += "```\n";
       if (opts.save) {
         const outFile = join2(dd, p, "..", `${p}.md`);
-        writeFileSync(outFile, `# ${p} — Spec Graph
+        writeFileSync(outFile, `# ${p} : Spec Graph
 
 ${out}`);
         console.log(source_default.green(`  ✓ ${outFile}`));
@@ -3275,7 +3312,209 @@ ${out}`);
     }
   }
 });
-program2.command("serve [dir]").description("MCP server — expose .dag graph to AI agents over stdio").action((d = ".") => serve(d));
+program2.command("serve [dir]").description("MCP server : expose .dag graph to AI agents over stdio").action((d = ".") => serve(resolvePath2(d)));
+program2.command("analyze [dir]").description("Analyze a spec project : score, gaps, suggestions").option("-p, --project <name>").action((d = ".", opts) => {
+  const dir = resolvePath2(d);
+  const dirs = [join2(dir, "projects"), join2(dir, "specs"), dir];
+  console.log(source_default.bold(`
+Spec Analysis
+`));
+  let found = false;
+  for (const dd of dirs) {
+    if (!existsSync2(dd))
+      continue;
+    const projects = readdirSync2(dd, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    for (const p of projects) {
+      if (opts.project && p !== opts.project)
+        continue;
+      const pd = join2(dd, p, "specs");
+      if (!existsSync2(pd))
+        continue;
+      const files = readdirSync2(pd).filter((f) => f.endsWith(".dog"));
+      if (!files.length)
+        continue;
+      found = true;
+      console.log(source_default.bold(`
+  ${p}`));
+      console.log("  " + "─".repeat(50));
+      const allEntities = [];
+      const allRelationships = [];
+      const analyses = [];
+      for (const f of files) {
+        const content = readFileSync2(join2(pd, f), "utf-8");
+        const ast = parse(content);
+        const entities = ast.sections.flatMap((s) => s.blocks.filter((b) => b.kind === "entity"));
+        const rels = ast.sections.flatMap((s) => s.blocks.filter((b) => b.kind === "relationship"));
+        allEntities.push(...entities);
+        allRelationships.push(...rels);
+        analyses.push({ file: f, sections: ast.sections.length, size: content.length, entities: entities.length, rels: rels.length });
+      }
+      const missingReq = ["SPEC.dog", "constitution.dog", "data-model.dog"].filter((f) => !files.includes(f));
+      const missingOpt = ["COPY.dog", "plan.dog", "DESIGN-SYSTEM.dog", "INDEX.dog"].filter((f) => !files.includes(f));
+      let score = 100 - missingReq.length * 15 - missingOpt.length * 5;
+      const noDesc = allEntities.filter((e) => !e.description || e.description.length < 10).length;
+      score = Math.max(0, score - noDesc * 3);
+      const noProps = allEntities.filter((e) => Object.keys(e.properties).length === 0).length;
+      score = Math.max(0, score - noProps * 5);
+      const noStates = allEntities.filter((e) => e.states.length === 0).length;
+      score = Math.max(0, score - noStates * 3);
+      console.log(`  ${files.length} files | ${score}% complete`);
+      for (const a of analyses) {
+        const detail = a.entities > 0 ? ` (${a.entities} entities, ${a.rels} rels)` : "";
+        console.log(source_default.gray(`    ${a.file} : ${a.sections} sections, ${(a.size / 1024).toFixed(1)}KB${detail}`));
+      }
+      const gaps = [];
+      for (const f of missingReq)
+        gaps.push(`\uD83D\uDD34 ${f}: Missing required file`);
+      for (const f of missingOpt)
+        gaps.push(`\uD83D\uDFE1 ${f}: Missing optional file`);
+      const entityNames = new Set(allEntities.map((e) => e.name));
+      for (const e of allEntities) {
+        if (!e.description || e.description.length < 10)
+          gaps.push(`\uD83D\uDFE1 ${e.name}: No description`);
+        if (Object.keys(e.properties).length === 0)
+          gaps.push(`\uD83D\uDFE1 ${e.name}: No properties defined`);
+        if (e.states.length === 0)
+          gaps.push(`\uD83D\uDD35 ${e.name}: No states defined`);
+      }
+      for (const r of allRelationships) {
+        if (r.source && !entityNames.has(r.source))
+          gaps.push(`\uD83D\uDFE1 Relationship: unknown source "${r.source}"`);
+        if (r.target && !entityNames.has(r.target))
+          gaps.push(`\uD83D\uDFE1 Relationship: unknown target "${r.target}"`);
+      }
+      if (gaps.length > 0) {
+        console.log(source_default.bold(`
+  Gaps (${gaps.length})`));
+        for (const g of gaps)
+          console.log(`  ${g}`);
+      } else
+        console.log(source_default.green(`
+  No gaps found.`));
+    }
+  }
+  if (!found)
+    console.log(source_default.yellow("No spec projects found. Run: dotdog init <project>"));
+});
+program2.command("generate [dir]").description("Generate missing spec files from SPEC.dog").option("-p, --project <name>").action((d = ".", opts) => {
+  const dir = resolvePath2(d);
+  const dirs = [join2(dir, "projects"), join2(dir, "specs"), dir];
+  let specContent = "", specDir = "";
+  for (const dd of dirs) {
+    if (!existsSync2(dd))
+      continue;
+    const projects = readdirSync2(dd, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    for (const p of projects) {
+      if (opts.project && p !== opts.project)
+        continue;
+      const pd = join2(dd, p, "specs");
+      const sp = join2(pd, "SPEC.dog");
+      if (existsSync2(sp)) {
+        specContent = readFileSync2(sp, "utf-8");
+        specDir = pd;
+        break;
+      }
+    }
+    if (specContent)
+      break;
+  }
+  if (!specContent) {
+    console.log(source_default.red("No SPEC.dog found. Create one first."));
+    return;
+  }
+  console.log(source_default.bold(`
+Spec Generator
+`));
+  console.log(source_default.gray(`  Source: ${specDir}/SPEC.dog
+`));
+  const ast = parse(specContent);
+  const entities = ast.sections.flatMap((s) => s.blocks.filter((b) => b.kind === "entity"));
+  const uiStrings = [];
+  for (const section of ast.sections) {
+    const h = section.heading.toLowerCase();
+    if (h.includes("what the user sees") || h.includes("screen")) {
+      const text = section.blocks.filter((b) => b.kind === "prose").map((b) => b.content).join(`
+`);
+      for (const m of text.match(/\[([^\]]+)\]/g) || [])
+        uiStrings.push({ screen: section.heading, element: "button", text: m });
+      for (const m of text.match(/"([^"]+)"/g) || [])
+        uiStrings.push({ screen: section.heading, element: "label", text: m });
+    }
+  }
+  if (!existsSync2(join2(specDir, "data-model.dog")) && entities.length > 0) {
+    let dm = `# Data Model
+
+## Core Entities
+
+`;
+    for (const e of entities) {
+      dm += `### Entity: ${e.name}
+
+${e.description || "No description."}
+
+`;
+      dm += "```yaml\n";
+      dm += `entity: ${e.name}
+`;
+      dm += `type: entity
+`;
+      dm += `properties:
+`;
+      for (const [k, v] of Object.entries(e.properties)) {
+        dm += `  ${k}:
+`;
+        dm += `    type: ${v.type}
+`;
+        if (v.required)
+          dm += `    required: true
+`;
+      }
+      if (e.states.length > 0)
+        dm += `states: [${e.states.join(", ")}]
+`;
+      dm += "```\n\n";
+    }
+    writeFileSync(join2(specDir, "data-model.dog"), dm);
+    console.log(source_default.green(`  ✓ data-model.dog (${entities.length} entities)`));
+  }
+  if (!existsSync2(join2(specDir, "COPY.dog")) && uiStrings.length > 0) {
+    let copy = `# App Copy
+
+| Screen | Element | Copy |
+|--------|---------|------|
+`;
+    for (const s of uiStrings)
+      copy += `| ${s.screen} | ${s.element} | ${s.text} |
+`;
+    writeFileSync(join2(specDir, "COPY.dog"), copy);
+    console.log(source_default.green(`  ✓ COPY.dog (${uiStrings.length} strings)`));
+  }
+  if (!existsSync2(join2(specDir, "INDEX.dog"))) {
+    let idx = `# INDEX
+
+| You are... | Start here | Then... |
+|------------|-----------|---------|
+`;
+    idx += `| Developer | SPEC.dog | data-model.dog → plan.dog |
+`;
+    idx += `| AI agent | data-model.dog | COPY.dog → SPEC.dog |
+`;
+    idx += `| Designer | SPEC.dog | COPY.dog |
+`;
+    writeFileSync(join2(specDir, "INDEX.dog"), idx);
+    console.log(source_default.green("  ✓ INDEX.dog"));
+  }
+  console.log(source_default.bold(`
+Run dotdog validate to verify.
+`));
+});
+program2.command("simulate <scenario>").description("Run a simulation scenario (phase 1 stub)").option("-p, --project <name>", "Project name", "default").action((scenario, opts) => {
+  console.log(source_default.bold(`
+Simulation: ${scenario} (project: ${opts.project})
+`));
+  console.log(source_default.gray("Simulation engine : reads SPEC.dog scenarios, walks through steps, checks pre/postconditions."));
+  console.log(source_default.gray("Full engine coming in a future release."));
+});
 program2.command("staleness [dir]").action((d = ".") => {
   const dir = resolvePath2(d);
   const dirs = [join2(dir, "projects"), join2(dir, "specs"), dir];
@@ -3334,6 +3573,13 @@ program2.command("staleness [dir]").action((d = ".") => {
     }
   }
 });
+program2.command("woof").action(() => {
+  console.log("  / \\__");
+  console.log(" (    @\\___");
+  console.log("  /       O");
+  console.log(" /   (_____/");
+  console.log("/_____/   U");
+});
 program2.parse();
 export {
   parseToJSON,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dotdog",
-  "version": "0.2.5",
-  "description": "The spec dog \u2014 validate, analyze, parse, and generate .dog spec genome files",
+  "version": "0.3.1",
+  "description": "CLI tool for structured software specifications. Validate .dog files, compile .dag graphs, query via MCP.",
   "type": "module",
   "main": "dist/cli.js",
   "bin": {
@@ -15,17 +15,29 @@
     "LICENSE"
   ],
   "keywords": [
-    "spec",
-    "dogfood",
     "specification",
-    "ai",
-    "documentation",
-    "dotdog",
-    "dog"
+    "cli",
+    "mcp",
+    "graph",
+    "dag",
+    "yaml",
+    "markdown",
+    "spec-driven-development"
   ],
   "license": "MIT",
   "author": "specdog",
-  "repository": "github:specdog/dotdog",
+  "homepage": "https://github.com/specdog/dotdog#readme",
+  "bugs": {
+    "url": "https://github.com/specdog/dotdog/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/specdog/dotdog.git",
+    "directory": "packages/dotdog"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "commander": "^15.0.0",
     "chalk": "^5.6.0"