Running Your First CDR Scan

This tutorial walks you through running a CDR scan on your workspace — from starting the pipeline to browsing the knowledge assets it produces.

Before you start

Make sure you have:

• A workspace with at least one repository registered
• The workspace's source code that you want to scan

Step 1: Open the CDR Pipeline

From the Workspace Browser:

1. Click Knowledge in the sidebar (or navigate to /knowledge)
2. Click CDR Pipeline tab

You'll see the pipeline control panel:

┌─ CDR Pipeline ───────────────────────────────────────┐
│                                                      │
│  Status: Ready to scan                               │
│  Scope: Entire workspace (2 repos)                   │
│                                                      │
│  ┌─ Pipeline Stages ─────────────────────────────┐   │
│  │  ○ Bootstrap                                  │   │
│  │  ○ Entries Candidate                          │   │
│  │  ○ Behavior Mining                            │   │
│  │  ○ State Machine                              │   │
│  │  ○ Domain Analysis                            │   │
│  │  ○ Document Generation                        │   │
│  └───────────────────────────────────────────────┘   │
│                                                      │
│  [Start Scan]  [Select Scope]                        │
└──────────────────────────────────────────────────────┘

Step 2: Choose scope

Click Select Scope to choose what to scan:

• Entire workspace — all registered repos (recommended for first scan)
• Specific repos — choose individual repositories
• Specific paths — scan a subset of files

For your first scan, select Entire workspace.

Step 3: Start the scan

Click Start Scan. The pipeline begins:

┌─ CDR Pipeline ───────────────────────────────────────┐
│  Scanning...                                          │
│                                                      │
│  ■ Bootstrap               ✓   (0.3s)               │
│  ■ Entries Candidate       ✓   (1.2s, 48 entries)   │
│  ■ Behavior Mining         ⟳   (in progress...)     │
│  ■ State Machine           ○                        │
│  ■ Domain Analysis         ○                        │
│  ■ Document Generation     ○                        │
│                                                      │
│  Progress: ████████░░░░ 40%                          │
└──────────────────────────────────────────────────────┘

Each stage lights up as it completes. You can watch the progress in real time.

Step 4: Browse the results

When the scan completes, click Browse Results. You'll see the Cognitive Portal:

┌─ Cognitive Portal ───────────────────────────────────┐
│  Search: [_______________]                            │
│                                                      │
│  ┌─ By Type ────────────────────────────────────┐    │
│  │  Behaviors        237 findings               │    │
│  │  Business Rules    42 findings               │    │
│  │  State Machines    12 findings               │    │
│  │  Evidence          891 sources               │    │
│  │  Domains            8 domains                │    │
│  └────────────────────────────────────────────────┘    │
│                                                      │
│  ┌─ Recent Findings ────────────────────────────┐    │
│  │  🔍 Behavior: SearchBar.onSubmit → ...       │    │
│  │  🔍 Business Rule: Free shipping over $100  │    │
│  │  🔍 State Machine: Order lifecycle           │    │
│  └────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────┘

What to look at first

If you want to...	Start with
Understand how components interact	Behaviors — shows call chains between components
Find business logic you didn't know existed	Business Rules — extracted rules from code
Trace state transitions	State Machines — visual transition maps
Verify findings	Evidence — each finding links to source code
See the big picture	Domains — entities grouped by business domain

What the output looks like

A behavior finding:

kind: behavior
name: SearchBar.onSubmit → ProductList.filter
evidence: fact
sources:
  - path: src/components/SearchBar.tsx
    line: 42
    snippet: "onSubmit={(q) => setFilter(q)}"
  - path: src/components/ProductList.tsx
    line: 18
    snippet: "useEffect(() => { fetchProducts(filter) }, [filter])"

A business rule:

kind: business-rule
name: Free shipping threshold
rule: Orders with total > $100 qualify for free shipping
domain: Order Management
sources:
  - path: src/services/shipping.ts
    line: 15
    snippet: "if (orderTotal > 100) { shippingCost = 0 }"

A state machine:

kind: state-machine
name: Order lifecycle
states:
  - Pending → Paid (on payment success)
  - Paid → Shipped (on fulfillment)
  - Shipped → Delivered (on delivery confirmation)
  - Any → Cancelled (on cancellation request)

Step 5: Use the knowledge

Now that your codebase is scanned, you can:

1. Navigate — browse by type, search by keyword, follow evidence links to source code
2. Inject — send the cognitive index to your agent as context before creating features
3. Reference — link to CDR findings in feature descriptions ("See Business Rule #42 for shipping logic")

Troubleshooting

Problem	Likely cause	Solution
Scan fails immediately	Project not parseable	Check that your source files are valid (syntax errors can block parsing)
No behaviors found	Entrypoints not detected	Try specifying entrypoints manually in the CDR config
"Too many files" warning	Large codebase	Reduce scope — scan specific repos or paths instead of the entire workspace
Scan takes too long	Large codebase with many files	CDR scales with file count. Run on specific repos or reduce scope
Unexpected results	Code patterns not recognized	CDR scanners work best with standard patterns. Unusual or highly abstracted code may produce fewer findings

Next steps

• CDR Overview — deeper dive into how CDR works
• Injecting Context — send CDR findings to your agent
• Audit Trail — every decision, recorded