The documentation is organized by what the reader needs, following Diátaxis. Architecture follows arc42, and decisions are recorded as ADRs.
| Section | Type | Read it when you want to… |
|---|---|---|
| product/ | Explanation | understand what Kintsugi is, why it exists, and where it is going |
| methodology/ | Explanation | understand the migration delivery method Kintsugi supports |
| architecture/ | Explanation (arc42) | understand how the system is designed, and why |
| decisions/ | Record | see what was decided, what is still open, and the ADRs |
| reference/ | Reference | look up exact facts: agents, MCP tools, CLI, data model, repo layout, configuration, terms |
| guides/ | How-to | accomplish a task: install, configure, work on a migration task |
| development/ | Delivery record | review implementation status, plans, open work, and verification evidence |
Start with Your first modernization project for a walkthrough of the implemented development flow. Release and client-compatibility limits are stated in the linked references.
Product
Methodology
- Delivery pipeline: phases P0–P4, gates, scorecard priority
- AI metrics: definitions, targets, data sources
Architecture (index)
| arc42 section | Document |
|---|---|
| 1 | Introduction and goals |
| 2 | Constraints |
| 3 | Context and scope |
| 4 | Solution strategy |
| 5 | Building block view |
| 6 | Runtime view |
| 7 | Deployment view |
| 8 | Crosscutting concepts (runtime & harnesses, Git as source of truth, security, identity, LLM configuration, observability) |
| 9 | Decisions |
| 10 | Quality requirements |
| 11 | Risks and technical debt |
| 12 | Glossary |
Decisions
Reference
- Glossary
- Runtime agents: job contract, agent definition, kernel tools, events
- Debug MCP server: the read-only tools of a development installation over runs, sandboxes, logs, queues and the database (ADR-0056)
- Job workspace: the layout of a job's workspace, the guide, attempts, the ledger and the lifecycle (ADR-0055)
- Data model
- Document repository layout: the numbered layout, each application split into legacy and modern (ADR-0051), who writes what and auto-commit
- Document formats: the Markdown shapes of every committed document (front matter, tables, cards)
- Document repo contexts: the context map, the Unit aggregate and the ubiquitous language
- Manifest schema:
kintsugi.yaml - Runtime web search and fetch: optional public-web tools, outbound permissions, guarded page retrieval and shared budgets
- Project memory: live learned/reviewed notes, daily logs, scratchpads and recovery shared by project agents
- The Brain: the vectorless tree index of a document repository branch that members' agents reason over and cite
- Document identifiers: compact stable RULE, SEC and GAP references, scope allocation and ledgers
- Item catalog: catalog items, stable IDs, and the units they become
- Document write path: job outputs, branches and pull requests
- Document reads and stage results: file APIs and result views
- Commit conventions: identity, trailers and auto-commit defaults
- Unit files: the unit directory, unit state, rule verdicts and traceability
- Design templates: design sets, template directives, checks, conformance (ADR-0044, ADR-0045)
- Specification profiles: the sections of an AS-IS specification by item kind (ADR-0060)
- Configuration: installation environment variables
Guides
- Deploy with the published Docker images
- Your first modernization project
- Member guideline: connect your AI client
- Install Kintsugi
- Build a project (register repos, write standards)
- Resolve questions and generate a design: final readiness, deliberate drafts and answers in the original documents
- Define a project's design templates
- Configure LLM providers for the runtime
Delivery record
- Member CLI and local MCP bridge: install the CLI, connect a client, sign in, add plugins, read projects and documents
- Guideline: the portal page
/guidelineon every installation (quick start, install, connect, plugins, reference) - Member client compatibility: tested client versions and setup probes
- Member client capabilities: what Claude Code, Codex and GitHub Copilot support for plugins, hooks and transcripts
- Plugin workflow audit: readiness, drafts, in-place question resolution and verification limits
- Known-answer eval: measure what a model writes with the built-in plugins on a fixture whose facts are known (ADR-0084)
- Brain eval: measure how a member's agent answers from a project's documents with the Brain and without it (ADR-0091)
- Implementation and verification record: the deployment work, its status and evidence; remaining release work
- Language: English. Keep documents neutral: no customer, vendor-internal or company-specific references.
- One purpose per document. Do not mix how-to steps into explanation pages; link instead.
- Single source of truth. Facts live in one place (usually
reference/or an ADR); other pages link to them rather than repeating them. - File names: lowercase kebab-case. arc42 chapters keep their number prefix.
- Decisions: any change to architecture, infrastructure dependencies or contracts needs an ADR (copy template.md) and an update to the decision register.
- Status markers: ✅ decided · 🟡 proposed · ⬜ open · ❓ open point inside a page (with its decision ID, e.g. D29).
- Product not implemented yet: guides describe planned behavior and say so at the top.