# AgentTeam Insight `graph` — smoke & dashboard verification

This document is the manual gate for verifying the AgentTeam Insight `graph`
subcommand against the upstream Understand-Anything (UA) TypeScript validator
and dashboard. It is the verification entry point reviewers and operators use
before treating the currently implemented path as dashboard-compatible.

This smoke verifies the deterministic convergence path covered so far. It does
not claim full UA original-pipeline parity; remaining scanner, batching,
LLM file-analyzer quality, exact tree-sitter/path-alias multi-language parity,
richer non-code extraction, real LLM assemble/graph-review quality, and
architecture/tour-builder LLM work is tracked by the #t1480 parity audit.
#t1486 adds deterministic `review.json`, `--review` existing-graph reuse,
file-level calls-flow tours, `tested_by` synthesis, and locale prompt
addendum wiring; those remain scoped deterministic gates, not LLM parity
claims.

The same steps run automatically via `kits/agentteam-insight/scripts/smoke-graph-builder.sh`.

## Audience

- Reviewers running the final implementation gate.
- Operators who want to validate a AgentTeam Insight build against UA locally.
- Engineers debugging a graph that the UA dashboard rejects.

## Prerequisites

- Go 1.25+ toolchain.
- Node.js 22+ for the UA parity step.
- A built Understand-Anything checkout at `~/devel/ai/Understand-Anything` (or
  pointed at by `UNDERSTAND_ANYTHING_ROOT`). Build it once:

  ```bash
  cd "$UNDERSTAND_ANYTHING_ROOT/understand-anything-plugin"
  corepack pnpm install --frozen-lockfile
  corepack pnpm --filter @understand-anything/core build
  ```

  When UA is absent the smoke script skips the parity step with a clear
  message — the rest of the smoke still runs and asserts the four artifacts.

## One-shot smoke (recommended)

From a AgentTeam Insight checkout:

```bash
kits/agentteam-insight/scripts/smoke-graph-builder.sh
```

The script:

1. Builds `agentteam-insight` from the current checkout.
2. Copies `kits/agentteam-insight/testdata/smoke/fixture-repo` into a tempdir so the
   source fixture never mutates.
3. Runs `agentteam-insight graph --input <tmp>/repo --mode full --no-prompt` so the Go-first non-interactive smoke auto-accepts the generated/found `.agentteam-insightignore` confirmation.
4. Asserts the four Graph Builder persisted artifacts exist and are non-empty:
   - `.agentteam-insight/knowledge-graph.json`
   - `.agentteam-insight/meta.json`
   - `.agentteam-insight/fingerprints.json`
   - `.agentteam-insight/config.json`
5. Asserts `.agentteam-insight/intermediate/review.json` exists and records
   the deterministic final review gate.
6. Asserts `.agentteam-insight/domain-graph.json` is NOT produced (Batch 7
   scope excludes the domain graph).
7. Pipes the generated `knowledge-graph.json` through
   `scripts/validate-ua-graph.mjs` and asserts UA `validateGraph()` returns
   `success: true` with no fatal validation error.

Pass a real repo to smoke against it instead of the fixture:

```bash
kits/agentteam-insight/scripts/smoke-graph-builder.sh /path/to/real/repo
```

## Manual reproduction

If you need to walk through each step by hand:

```bash
# 1. Build agentteam-insight.
cd kits/agentteam-insight && go build -o /tmp/agentteam-insight .

# 2. Run full mode against a fixture copy (so you don't mutate the source).
fixture="$(mktemp -d)/repo"
cp -R testdata/smoke/fixture-repo "${fixture}"
/tmp/agentteam-insight graph --input "${fixture}" --mode full --no-prompt

# 3. Verify the Graph Builder artifacts and deterministic review artifact.
ls "${fixture}/.agentteam-insight/"
ls "${fixture}/.agentteam-insight/intermediate/review.json"
# Expect: config.json  fingerprints.json  knowledge-graph.json  meta.json
#         intermediate/review.json (no domain-graph.json, no diff-overlay.json)

# 4. Run the UA validator.
UNDERSTAND_ANYTHING_ROOT=/path/to/Understand-Anything \
  node scripts/validate-ua-graph.mjs "${fixture}/.agentteam-insight/knowledge-graph.json"
# Expect: {"success":true,"fatal":null,"issues":[],"dataSummary":{...}}
```

## Dashboard smoke

The compatibility dashboard renders `.agentteam-insight/` directly. After the smoke
produces a graph, point the dashboard at the tempdir:

```bash
cd "$UNDERSTAND_ANYTHING_ROOT/understand-anything-plugin/packages/dashboard"
GRAPH_DIR=/path/to/smoke-fixture pnpm dev
```

Open the printed Vite URL. The dashboard must:

- Load `knowledge-graph.json`, `meta.json`, `fingerprints.json`, `config.json`
  without console errors.
- Render the fixture graph nodes and surviving edges (`imports`, `contains`,
  `calls`) produced by `agentteam-insight graph`.
- Show deterministic layers that contain only file-level nodes, with every
  file-level node assigned to exactly one layer, plus the deterministic
  file-level tour with no "node not found" warnings.
- No fatal validation toast — the dashboard's own `validateGraph()` runs on
  load and matches the smoke script's verdict.

If the dashboard surfaces a validation error the smoke missed, capture the
exact issue JSON and update `validate-ua-graph.mjs`'s expected output. The
compat harness and dashboard must agree.

## What this smoke does NOT cover

- **Incremental mode.** The `--mode incremental` and `--mode auto` paths are
  covered by `internal/graphbuilder/run_test.go`. The smoke focuses on the
  full→dashboard compatibility contract because that is the path operators
  first hit.
- **Full UA semantic parity.** #t1482 covers scanner/ignore pre-flight
  mechanics, #t1483 covers the batch/neighborMap analyzer seam plus batch
  output contract, #t1484 covers the final scan-result contract plus an
  explicit file-analyzer command-runner seam, #t1485 covers lightweight
  10-family import/structure extraction plus scoped non-code child nodes, and
  #t1486 covers deterministic review/tour/merge enhancements. Smoke/default
  runs remain deterministic. #t1491 adds scoped pure-Go Louvain/community
  batching. #t1505 documents but does not implement the remaining production
  OpenCode/skills hardening gaps: server-backed runner lifecycle, session-local
  source subset copying with external directory reads denied, and allowlisted
  skills materialization. Exact graphology fixture equivalence,
  tree-sitter/path-alias resolver parity, richer multi-language/non-code
  extraction, real LLM assemble/graph-review quality, and
  architecture/tour-builder LLM parity also remain documented gaps under the
  #t1480 audit.
- **Domain graph.** `domain-graph.json` generation is intentionally not
  implemented in this batch; the smoke asserts its absence.
- **Diff overlay.** `diff-overlay.json` is only written by the incremental
  path when upstream semantics change; the smoke (full mode) asserts its
  absence.