# AgentTeam Insight Graph Builder PR body

## Proposed PR title

```text
feat(agentteam-insight): add graph builder and wiki workflows
```

## Problem Summary

- The repository insight kit should ship as **AgentTeam Insight**, not as an internal
  porting story or legacy command surface.
- The public CLI should be limited to graph building and wiki generation:
  `agentteam-insight graph` and `agentteam-insight wiki`.
- Graph artifacts should use AgentTeam Insight naming (`.agentteam-insight/` and
  `.agentteam-insightignore`) while keeping a bounded compatibility gate for the
  existing graph JSON schema consumers.
- #t1501–#t1504 have converged the naming/CLI/artifact/docs/Web release
  surface. #t1505 lands the implementation for the three OpenCode/skills
  blockers that previously blocked `/merge`: server-backed file-analyzer
  runner, source-subset permission boundary, and Graph Builder skills
  materialization. Real LLM quality parity (architecture-analyzer /
  tour-reviewer / inline review) remains a follow-up batch.

## What is changed and how it works?

- Adds the `kits/agentteam-insight` Go module at `github.com/tidbcloud/AgentTeam/kits/agentteam-insight`.
- Converges the CLI to:

  ```bash
  agentteam-insight graph --input <repo> [--output <root>] [--mode full|incremental|auto]
  agentteam-insight wiki --input <repo-or-insight-output> --output <wiki-repo>
  ```

- Removes the old public `analyze` command and legacy graph command aliases.
- Implements the deterministic Graph Builder pipeline:
  - scan repository files with `.agentteam-insightignore` and `.gitignore` filters;
  - extract Go and lightweight generic multi-language structure;
  - resolve import/call edges and suppress dangling references;
  - build deterministic batches with neighbor maps and community-style grouping;
  - assemble full/incremental graph JSON with fingerprint-based change
    classification;
  - write `.agentteam-insight/{knowledge-graph,meta,fingerprints,config}.json` plus
    reproducible `intermediate/` diagnostics;
  - generate deterministic layer, tour, and review artifacts by default.
- Keeps `agentteam-insight wiki` as the wiki generation surface for repository wiki
  Markdown generation.
- Documents the release-facing AgentTeam Insight / Graph Builder narrative used for
  the PR title and description; the parallel Web/KB automation split updates
  generated presets and progress UI to the same vocabulary.

## User Behavior Changes

- Users run `agentteam-insight graph` to build repository graph JSON artifacts.
- Users run `agentteam-insight wiki` to generate wiki Markdown from source repos and
  optional Graph Builder outputs.
- Graph artifacts are written under `.agentteam-insight/` and filtered through
  `.agentteam-insightignore`.
- Automation Hub generated `Codebase KB` workflow wording is handled in the
  parallel Web/KB automation split, using the same `agentteam-insight graph` and
  `agentteam-insight wiki` terminology.

## Compatibility Notes

- Graph JSON compatibility is enforced through isolated compat tests and the
  optional smoke validator script.
- The default AgentTeam Insight path is deterministic and does not require an external
  checkout or Node runtime.
- #t1505 lands the three OpenCode/skills blockers previously tracked as
  follow-up:
  - **Production server-backed runner** (`kits/agentteam-insight/internal/opencodeclient/`):
    `--opencode-server auto` manages one `opencode serve` process per graph
    Run() (random per-run Basic Auth password, `--hostname 127.0.0.1 --port
    <random>`, polls `GET /global/health`); the per-batch HTTPClient speaks
    the real wire protocol — `POST /session` with `x-opencode-directory`,
    `POST /session/:id/prompt_async`, `GET /event` SSE filtered by sessionID
    until `session.status=idle`, `DELETE /session/:id` for best-effort
    cleanup. Fake-led integration tests prove exactly-once Start/Stop and
    paired Open/Close on success + failure paths; a httptest-backed protocol
    test proves the wire format against a fake server that mirrors
    `opencode serve`.
  - **File-analyzer source subset + permission boundary**
    (`kits/agentteam-insight/internal/graphbuilder/sourcestage/`):
    `request.files` are copied into `workDir/sources/<relative-path>` with
    sha256 idempotency; absolute / drive-letter / parent-traversal paths,
    symlinks, and non-regular files are rejected; `opencode.json` sets
    `external_directory: deny`; manifest `projectRoot` points at `sources/`
    and a `sourceMap` block cites original repository coordinates.
  - **Graph Builder skills materialization/allowlist**
    (`kits/agentteam-insight/internal/graphbuilder/skillsmanifest/`):
    `//go:embed` allowlists `agentteam-insight/file-analyzer/SKILL.md`; the
    runner materializes `.agents/skills/{agentteam-insight/...,
    skills-manifest.json}` (bundleVersion + sha256) per workDir, prunes
    stale agentteam-insight entries, preserves user-owned skills outside the
    allowlist, and is idempotent + concurrent-workDir safe.
- Real LLM quality parity (architecture-analyzer / tour-reviewer / inline
  review at UA parity) is the remaining follow-up and is **not** in scope
  for #t1505. The deterministic pipeline + file-analyzer seam are production
  ready; the LLM-driven review passes plug into the existing reviewer
  interface in a separate batch.

## Tests

- Implementation gates through #t1503 passed before this PR-body rewrite:
  - `cd kits/agentteam-insight && go test ./... -count=1`
  - `cd kits/agentteam-insight && go build -o /tmp/agentteam-insight .`
  - `cd kits/agentteam-insight && scripts/smoke-graph-builder.sh`
- #t1504 release-surface docs/PR metadata split:
  - `git diff --check`
  - non-Web legacy naming grep gate for old public kit names, artifact paths, and schema-title strings
- The parallel Web/KB automation split owns the focused Web tests and KB progress display/wire verification before the final PR metadata update.
- #t1505 implementation gate (this batch):
  - `cd kits/agentteam-insight && go test ./...` — full kit green, including
    new `sourcestage` (5 cases), `skillsmanifest` (7 cases),
    `opencodeclient` (fake-led 9 + httptest protocol 5), and 6
    server-backed graphbuilder integration tests covering exactly-once
    Start/Stop, paired Open/Close on success + Invoke failure + Open
    failure paths, and explicit-addr mode without managed Start/Stop.
  - `git diff --check`
  - grep gate: file-analyzer `opencode.json` `external_directory: deny`;
    manifest `projectRoot` points at `sources/`.
  - `agentteam-insight graph -h` exposes `--opencode-server`.