feat: add observed workspace facts

README.md

@@ -9,21 +9,22 @@
 [![Install in VS Code](https://img.shields.io/badge/Install_in_VS_Code-0098FF?logo=visualstudiocode)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522dotdog%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522dotdog%2540latest%2522%252C%2522serve%2522%255D%257D)
 [![Install in Cursor](https://img.shields.io/badge/Install_in_Cursor-1a1a1a?logo=cursor)](https://cursor.com/install-mcp?name=dotdog&config=%7B%22command%22%3A%22npx%20-y%20dotdog%40latest%20serve%22%7D)
 
-> **Spec-driven design for agent-ready projects.** Turn plans or existing repos into structured `.dog` specs, validate them, compile them into `.dag` graphs, and let agents query real project structure instead of guessing.
+> **Spec-driven design for agent-ready projects and workspaces.** Turn plans, repos, or multi-repo products into structured `.dog` specs, compile `.dag` graphs, and let agents query real project structure instead of guessing.
 
 ## What dotdog does
 
-dotdog is a spec-driven design toolchain.
+dotdog is a spec-driven design toolchain for single repos, monorepos, and polyrepo workspaces.
 
-It supports two starting points:
+It supports three starting points:
 
 1. **Empty project** — create a spec foundation before implementation.
-2. **Existing project** — map the current repo into a structured spec workspace.
+2. **Existing project** — map the current repo into structured graph facts.
+3. **Workspace product** — describe a product made from N repositories with `.doghouse/workspace.json`.
 
 The core flow:
 
 ```text
-plan -> spec workspace -> validation -> implementation graph -> agent execution
+plan -> spec workspace -> validation -> repo/workspace graph -> agent execution
 ```
 
 `.dog` files are the human-readable source specs. `.dag` files are compiled implementation graphs for agents and tools.
@@ -41,10 +42,20 @@ Requires Node.js >= 20 or Bun >= 1.3.
 ## Quick Start
 
 ```bash
-dotdog init my-project     # create a spec workspace
-dotdog validate            # check spec completeness
-dotdog compile             # build the .dag implementation graph
-dotdog serve               # expose the graph to MCP-compatible agents
+dotdog init my-project      # create a spec workspace
+dotdog validate             # check spec completeness
+dotdog compile              # build the .dag implementation graph
+dotdog serve                # expose the graph to MCP-compatible agents
+```
+
+For an existing product or organization workspace:
+
+```bash
+dotdog workspace init --id example-workspace
+dotdog workspace add ../example-service --alias example-service --role api
+dotdog workspace add ../example-interface --alias example-interface --role web
+dotdog workspace validate
+dotdog workspace graph --json
 ```
 
 ## What init creates
@@ -92,6 +103,40 @@ dotdog validate
 dotdog compile
 ```
 
+## Workspaces for N repos
+
+A Dotdog workspace is a product boundary. It can contain one repo, a monorepo, or N separate repositories.
+
+Workspace metadata lives in:
+
+```text
+.doghouse/workspace.json
+```
+
+Example:
+
+```json
+{
+  "version": 1,
+  "workspace": { "id": "example-workspace", "name": "example-workspace" },
+  "repos": [
+    { "alias": "example-service", "role": "api", "path": "../example-service" },
+    { "alias": "example-interface", "role": "web", "path": "../example-interface" }
+  ],
+  "groups": [],
+  "edges": []
+}
+```
+
+The workspace graph emits repo-qualified facts so humans and agents can distinguish where a fact came from:
+
+```text
+example-service:src/routes/core-flow.ts
+example-interface:src/features/core-flow/index.ts
+```
+
+No manifest is required for single-repo projects; Dotdog treats the current repo as a one-repo workspace by default.
+
 ## Repo mapping direction
 
 dotdog should not only scaffold empty projects. It should also map existing repos.
@@ -121,7 +166,13 @@ See [Spec-Driven Repo Mapping](docs/spec-driven-repo-mapping.md) for the formal
 | `dotdog tokens [dir]` | Count tokens in `.dog` files and compare to compiled `.dag` savings. |
 | `dotdog index [dir]` | Build search index for semantic queries across compiled specs. |
 | `dotdog search <query>` | Semantic search across compiled specs using the search index. |
-| `dotdog serve [dir]` | Start MCP server over stdio. AI agents query specs without hallucination. |
+| `dotdog serve [dir]` | Start MCP server over stdio. AI agents query specs and workspace metadata without hallucination. |
+| `dotdog workspace init --id <id>` | Create `.doghouse/workspace.json` for a repo or product workspace. |
+| `dotdog workspace add <path>` | Add a repository to the workspace manifest with `--alias` and `--role`. |
+| `dotdog workspace list` | List workspace repos and groups. Use `--json` for structured output. |
+| `dotdog workspace validate` | Validate workspace manifest aliases, paths, groups, and edges. |
+| `dotdog workspace graph` | Emit deterministic workspace graph JSON. |
+| `dotdog map [dir]` | Inspect an existing repo and generate graph-ready `.dog` facts plus `repo.dag`. |
 | `dotdog simulate <scenario>` | Walk through a scenario. Reads SPEC.dog scenarios, checks pre/postconditions. |
 | `dotdog predictions [dir]` | List all predictions with status (pending, correct, wrong, partial). |
 | `dotdog resolve <name>` | Mark a prediction as correct, wrong, or partial with evidence. |
@@ -139,7 +190,7 @@ Planned:
 | Command | Description |
 |---------|-------------|
 | `dotdog init <project> --map` | Create a spec workspace and seed it from the current repo. |
-| `dotdog map [dir]` | Inspect an existing repo and generate graph-ready `.dog` facts. |
+| Cross-repo trace/search | Infer relationships across workspace repos beyond explicit manifest edges. |
 
 ## File Formats
 
@@ -174,11 +225,11 @@ JSON graph compiled from `.dog` files. Nodes, edges, properties, and states in a
 Example graph facts:
 
 ```text
-CheckoutPage renders CartSummary
-CheckoutPage calls POST /api/checkout
-POST /api/checkout writes orders
-POST /api/checkout depends_on STRIPE_SECRET_KEY
-orders implemented_by prisma/schema.prisma
+CoreFlowPage renders StatusPanel
+CoreFlowPage calls POST /api/core-flow
+POST /api/core-flow writes records
+POST /api/core-flow depends_on SERVICE_TOKEN
+records implemented_by prisma/schema.prisma
 ```
 
 ## MCP Server : AI Agent Integration
@@ -193,11 +244,12 @@ orders implemented_by prisma/schema.prisma
 | `schema` | Property definitions only : zero prose, agent-optimized |
 | `summary` | Node count, edge count, file count, compile time |
 | `listProjects` | Array of project names |
+| `workspace.list` | Structured workspace metadata with repos, groups, and `trustedAsInstruction: false` |
 
 Agent workflow:
 
 ```text
-listProjects -> getEntity -> traverse graph
+workspace.list -> listProjects -> getEntity -> traverse graph
 ```
 
 ## Dogfood

docs/blog/ai-coding-agents-need-structured-specs.md

@@ -25,7 +25,7 @@ Here's a real-world product spec:
 
 ```
 Users can sign up with email and password. Each user belongs to one
-organization. Organizations have billing plans...
+organization. Organizations have access rules...
 ```
 
 An AI agent reads this and builds a user system. But it fills in blanks with plausible-sounding hallucinations:

docs/blog/dotdog-cursor.md

@@ -49,15 +49,15 @@ $ dotdog compile
 
 Then ask Cursor:
 
-You: Build a checkout flow for the Order entity
+You: Build a core-flow flow for the Order entity
 
 Cursor (agent mode):
   → getEntity("Order")
   → traverse("Order", 2)
   → getEntity("Payment")
   → getEntity("Cart")
 
-Generates complete checkout component with:
+Generates complete core-flow component with:
   - Order status flow (pending → confirmed → shipped)
   - Payment integration with exact field names
   - Cart-to-Order conversion

docs/blog/index.md

@@ -12,6 +12,7 @@ Notes on agent-first documentation, structured specs, MCP, ARD, and the agent in
 
 ## Posts
 
+- [Observed Workspace Graphs](observed-workspace-graphs) — June 24, 2026
 - [Google's Agentic Resource Discovery Is the Missing Layer of the Agent Internet](google-ard-dotdog) — June 18, 2026
 - [Karpathy's LLM OS Needs a Brain. Here's What That Looks Like.](karpathy-wiki-brain) — June 18, 2026
 - [Agent-First Documentation — The New Standard](agent-first-documentation) — June 17, 2026

docs/blog/karpathy-wiki-brain.md

@@ -54,7 +54,7 @@ Entity: Payment
     → Webhook: triggers
 
 Entity: Customer
-  Properties: email (string), payment_methods (array), billing_address (object)
+  Properties: email (string), display_name (string), preferences (object)
   States: active → suspended → deleted
   Relationships:
     → Payment: initiates

docs/blog/live-contracts.md

@@ -22,7 +22,7 @@ That's it. One command. dotdog scans your `.dog` files for `type: endpoint` enti
   ✓ memory-api
   ✓ user-api
   ⚠ search-api: https://backup.search.sh (backup, primary failed)
-  ✗ billing-api: https://api.billing.sh — missing fields: invoice_count
+  ✗ status-api: https://api.example.test — missing fields: status_code
 
   4 endpoints: 2 passed, 1 degraded, 1 failed
 ```

docs/blog/observed-workspace-graphs.md

@@ -0,0 +1,47 @@
+---
+layout: default
+title: "Observed Workspace Graphs"
+description: "dotdog observe, ask, and drift turn a software workspace into deterministic graph facts."
+---
+
+← [Blog](index)
+
+# Observed Workspace Graphs
+
+Most software tools treat a repository as a pile of files. Humans and agents then rediscover the same facts over and over: which files exist, which routes are present, which specs mention a behavior, which tests cover a surface, and which generated artifacts are stale.
+
+Dotdog's observed workspace graph is a deterministic snapshot of that reality.
+
+```bash
+dotdog observe
+dotdog ask "which files define routes?"
+dotdog drift
+```
+
+`dotdog observe` walks the current repo or workspace, maps implementation surfaces, and writes machine-readable artifacts under `.doghouse/`:
+
+```text
+.doghouse/observed.json
+.doghouse/facts.jsonl
+.doghouse/workspace.dag
+```
+
+The important unit is a cited graph fact. A fact has a subject, predicate, object, source, confidence, and optional repo/file location. That makes it small enough for tools to query and concrete enough for humans to inspect.
+
+```json
+{
+  "subject": "src/routes/status.ts",
+  "predicate": "is",
+  "object": "api_route",
+  "source": "code",
+  "confidence": "compiled"
+}
+```
+
+`dotdog ask` is intentionally deterministic. It does not need a model to answer basic workspace questions. It searches observed facts first and returns matching source paths.
+
+`dotdog drift` checks whether observed facts are missing, stale, or pointing at files that no longer exist. It is a local safety check before heavier automation, CI gates, or agent workflows.
+
+This gives Dotdog a simple public contract: map the workspace, write cited facts, query the facts, and report drift.
+
+The goal is not to replace source code or specs. The goal is to stop every person and every agent from starting at zero.

docs/index.md

@@ -61,6 +61,20 @@ You write specs before code. Five minutes to set up. Zero configuration.
 | Compile | `dotdog compile` | Build a positional DAG graph — 94% smaller, optimized for LLM context |
 | Expose | `dotdog serve` | Start an MCP server. AI agents query via six structured tools |
 
+## Observed workspace graph
+
+Dotdog can also observe an existing repo or multi-repo workspace and write deterministic graph artifacts:
+
+```bash
+dotdog observe
+dotdog ask "which files define routes?"
+dotdog drift
+```
+
+`observe` writes `.doghouse/observed.json`, `.doghouse/facts.jsonl`, and `.doghouse/workspace.dag`. `ask` queries those facts without an LLM dependency. `drift` reports stale or missing observed references.
+
+Read more: [Observed Workspace Graphs](blog/observed-workspace-graphs).
+
 ## For AI agents
 
 Six MCP tools for structured queries — no scanning, no guessing:

docs/spec-driven-repo-mapping.md

@@ -127,41 +127,41 @@ Agents should be able to ask:
 ## Example Map Output
 
 ```dog
-### Entity: CheckoutPage
+### Entity: CoreFlowPage
 
-Frontend checkout screen.
+Frontend core-flow screen.
 
 ```yaml
-entity: CheckoutPage
+entity: CoreFlowPage
 type: component
-file: src/app/checkout/page.tsx
+file: src/app/core-flow/page.tsx
 renders:
-  - CartSummary
+  - StatusPanel
 calls:
-  - POST /api/checkout
+  - POST /api/core-flow
 depends_on:
-  - NEXT_PUBLIC_STRIPE_KEY
+  - NEXT_PUBLIC_SERVICE_URL
 implements:
-  - Checkout Flow
+  - CoreFlow Flow
 ```
 
-### Entity: Checkout API
+### Entity: CoreFlow API
 
-Backend endpoint that creates checkout sessions.
+Backend endpoint that creates core-flow sessions.
 
 ```yaml
-entity: Checkout API
+entity: CoreFlow API
 type: api_route
-route: POST /api/checkout
-file: src/app/api/checkout/route.ts
+route: POST /api/core-flow
+file: src/app/api/core-flow/route.ts
 calls:
-  - Stripe Checkout Session
+  - CoreFlow Service
 writes:
-  - orders
+  - records
 depends_on:
-  - STRIPE_SECRET_KEY
+  - SERVICE_TOKEN
 implements:
-  - Checkout Flow
+  - CoreFlow Flow
 ```
 ```
 

docs/v0.9-plan.md

@@ -202,7 +202,7 @@ $ dotdog doctor
 
   Environment
   ✓ git 2.48.1
-  ✓ gh 2.65.0 (authenticated as logohere)
+  ✓ gh 2.65.0 (authenticated)
   ✓ node 26.3.0
   ✓ dotdog 0.8.4 (latest)
 

package.json

@@ -7,7 +7,7 @@
     "packages/*"
   ],
   "scripts": {
-    "build": "bun run --filter '*' build",
+    "build": "bun run --cwd packages/dotdog build",
     "lint": "bun run --filter '*' lint",
     "test": "bun test",
     "pack:check": "node scripts/check-pack.mjs",