Repository Structure

AI Legal UK · The Counsel is composed of four main components: the agent-host skill system, the Next.js web edition (The Counsel), the MCP servers (legislation + caselaw), and supporting scripts/templates.

Figure 1 — the 2026 system map.

Figure 1.a — the broadsheet rebrand of the older framing.

Figure 1.b — the original architecture plate, kept for reference.

Mermaid source — the diagram above is generated from this

flowchart TB
  subgraph A["I · Two editions, one canon"]
    direction LR
    CLI["CLI skills<br/>legal · skills · agents"]
    REG["skill-registry.json<br/>38 skills · 12 agents"]
    WEB["The Counsel — web<br/>Next.js 14 dashboard"]
    CLI --- REG --- WEB
  end
  subgraph P["II · Provider abstraction"]
    direction LR
    ANT[Anthropic]
    OAI[OpenAI]
    CDX[Codex CLI]
  end
  subgraph L["III · Live UK law"]
    direction LR
    LEG["legislation.gov.uk<br/>uk-legislation MCP"]
    CASE["caselaw MCP + Lex<br/>63,000 judgments"]
  end
  subgraph S["IV · Storage and auth"]
    direction LR
    NEON["Neon Postgres"]
    R2["Cloudflare R2"]
    CLERK["Clerk"]
  end
  REG --> P
  REG --> L
  WEB --> S

Directory Tree

ai-legal-uk/
├── legal/SKILL.md              — Main orchestrator (routes /legal commands)
├── skills/legal-*/SKILL.md     — 38 individual skill files
├── agents/legal-*.md           — 12 agent definitions (the panel)
├── dashboard/                  — Next.js 14 web application (The Counsel)
│   ├── app/                    — App Router pages and API routes
│   │   ├── api/                — Server-side route handlers
│   │   │   ├── review/         — Review endpoint (SSE + JSON)
│   │   │   ├── compare/        — Contract comparison (SSE + JSON)
│   │   │   ├── generate/       — Document generation
│   │   │   ├── anthropic/      — API key validation
│   │   │   ├── document/       — File extraction (text + OCR)
│   │   │   ├── caselaw/        — National Archives lookups
│   │   │   ├── legislation/    — legislation.gov.uk lookups
│   │   │   └── webhooks/clerk/ — Clerk user upsert + welcome email
│   │   ├── chambers/           — Active matters home
│   │   ├── review/             — Review pages
│   │   ├── compare/            — Comparison page
│   │   ├── legislation/        — Legislation browser
│   │   ├── skills/             — Skills catalog page (Library)
│   │   ├── generate/           — Document generator
│   │   ├── history/            — Review history
│   │   ├── matter/[id]/        — Matter detail view
│   │   ├── counsel/agents/     — The panel of twelve
│   │   ├── pricing/, /docs/, /onboarding/, /settings/
│   ├── components/             — Editorial UI primitives (components/counsel/)
│   ├── lib/                    — Core logic and utilities
│   │   ├── model-providers/    — Provider abstraction (Anthropic · OpenAI · Codex)
│   │   ├── api.ts              — runSkillAnalysis / streamSkillAnalysis
│   │   ├── api-route-utils.ts  — Request validation, error mapping
│   │   ├── document-extraction.ts — TXT/DOCX/PDF text extraction
│   │   ├── document-ocr.ts     — OCR fallback (OpenAI / Firecrawl)
│   │   ├── review-utils.ts     — Review lifecycle helpers
│   │   ├── matter-ownership.ts — resolveOwnedMatterId tenancy guard
│   │   ├── track-changes.ts    — DOCX redline pipeline (PizZip)
│   │   ├── word-draft.ts, word-draft-server.ts — Pure-TS DOCX generator
│   │   ├── skill-registry.json — Canonical skill register (single source of truth)
│   │   ├── skill-count.ts      — SKILL_COUNT / SKILL_COUNT_WORD helpers
│   │   ├── skills-data.ts      — Web-side skill catalog (mirrors registry)
│   │   ├── caselaw.ts, legislation.ts, live-commencement.ts — Live UK law
│   │   ├── db/                 — Drizzle ORM over Neon (users · matters · reviews · documents · audio_briefings)
│   │   ├── r2.ts               — Cloudflare R2 presigned uploads
│   │   ├── email.ts            — Resend welcome dispatch
│   │   └── demo-data/          — 12 demo review fixtures (zero API cost)
│   ├── proxy.ts                — Clerk middleware (auth-gated routes)
│   └── scripts/                — Smoke + benchmark automation
├── mcp-servers/                — Two local MCP servers
│   ├── uk-legislation/src/     — 6 legislation.gov.uk tools
│   └── caselaw/src/            — 10 National Archives judgment tools
├── doc-site/                   — VitePress public docs
├── scripts/
│   ├── generate_legal_pdf.py   — Python PDF report generator (ReportLab)
│   ├── audit_skills.mjs        — 38-skill ↔ 12-agent parity guardrail
│   └── audit_docs.mjs          — Registry ↔ docs parity check
├── samples/                    — Sample legal documents for testing
├── templates/                  — Report templates
├── install.sh                  — Install skills into ~/.claude/
├── uninstall.sh                — Remove installed skills
├── .mcp.json                   — MCP server configuration (uk-legislation · caselaw · lex)
├── CLAUDE.md                   — Project instructions for Claude Code
└── AGENTS.md                   — Mirror of CLAUDE.md for Codex and other AGENTS.md-aware hosts

Component Overview

Agent-Host Skills (legal/, skills/, agents/)

The primary CLI interface. Users run /legal <command> inside Codex, Claude Code, or another compatible agent host, and the orchestrator in legal/SKILL.md routes to the appropriate skill file. Skills are pure markdown prompts -- no compilation, no dependencies, no runtime code. Agents are launched by orchestrator skills for parallel analysis.

INFO

Skills and agents are installed into the configured host directory by running ./install.sh. They are removed with ./uninstall.sh.

Dashboard (dashboard/)

A Next.js 14 App Router application that provides a browser-based UI for the same analysis skills. Provider-pluggable via lib/model-providers/ — Anthropic, OpenAI, or OpenAI Codex CLI — selected by which kind of API key the user pastes in the browser. Supports both demo mode (free, using fixture data) and live mode (user provides their own provider API key). Built with shadcn/ui, Radix UI, and the editorial primitives in components/counsel/.

MCP Servers (mcp-servers/)

Two TypeScript MCP servers ship with the repo, plus one remote HTTP server. All three are registered in .mcp.json:

Entry	Type	Source	Purpose
uk-legislation	local stdio	mcp-servers/uk-legislation/	6 tools against legislation.gov.uk's XML API — search, lookup, in-force, amendments, extent
caselaw	local stdio	mcp-servers/caselaw/	10 tools against caselaw.nationalarchives.gov.uk — search, judgment lookup, summarise, by-judge / by-party
lex	remote HTTP	https://lex.lab.i.ai.gov.uk/mcp	63,000+ judgments with semantic search via the National Archives Lex Graph

Scripts (scripts/)

Supporting utilities, primarily generate_legal_pdf.py which generates professional A4 PDF reports using Python's reportlab library. Called by the legal-report-pdf skill.

Samples & Templates (samples/, templates/)

Sample legal documents for testing and development, and report templates used by the PDF generator.

Deployment Independence

The CLI skills and the dashboard are deployed independently:

Change	Affects
Edit skills/legal-review/SKILL.md	CLI skill surface only
Edit dashboard/lib/api.ts	Dashboard web UI only
Edit agents/legal-clauses.md	CLI skill surface only
Edit dashboard/lib/skills-data.ts	Dashboard skill catalog only

Both share the same conceptual skill definitions and jurisdiction scope, but there is no code-level dependency between them.