KindScript Documentation

Chapters

#	Chapter	What’s in it
1	Architecture	System overview, compiler pipeline, layers, data flow, source layout
2	Kind System	Kind syntax, TypeKind, instances, location resolution, scope validation, discovery
3	Constraints	All 6 constraint types (3 user-declared + 3 structural), plugin architecture
4	Decisions	Architecture Decision Records (32 ADRs: plugin vs LSP, drop .k.ts, unified Kind, etc.)
5	Examples	Real-world patterns: Clean Architecture, design systems, bounded contexts
6	Tutorial	Progressive walkthrough: first constraint to real-world modeling

Reading Order

Onboarding:

README.md — project overview
CLAUDE.md — development guide
architecture — system overview
tutorial-guide — step-by-step walkthrough

Implementing a feature:

architecture — relevant section
constraints — if adding/modifying constraints
tests/README.md — testing guide

Understanding a decision:

decisions/ — browse 32 ADRs by topic or chronologically

Quick Reference

Question	Chapter
How does the pipeline work?	architecture — Compiler Pipeline
How do I define a Kind?	kind-system — Kind Definitions
What constraints are available?	constraints — Constraint Types
How do I add a new constraint?	constraints — Adding a New Constraint Type
Why plugin instead of LSP?	decisions/0001-language-service-plugin-instead-of-custom-lsp.md
Why no .k.ts extension?	decisions/0009-drop-kts-piggyback-on-typescript-type-checker.md
How do I model a design system?	examples — Design System
How do bounded contexts work?	examples — Bounded Contexts
How do I learn KindScript step by step?	tutorial-guide — Tutorial
How do I use TypeKind?	kind-system — TypeKind
How does scope validation work?	kind-system — Scope Validation
How do I write tests?	tests/README.md — Testing guide

Directory Structure


docs/                                Source of truth (checked in)
├── README.md                        This file (index)
├── architecture               System overview + pipeline + layers
├── kind-system                Kind syntax + instances + discovery
├── constraints                All 6 constraints + plugin architecture
├── decisions/                       Architecture Decision Records (32 ADRs)
│   ├── README.md                    ADR index
│   ├── 0001-*.md                    Individual ADR files
│   └── template.md                  Template for new ADRs
├── examples                   Real-world modeling examples
├── tutorial-guide                   Progressive walkthrough + real-world narrative
└── archive/                         Historical — do not use for implementation
    ├── architecture/                V1–V4 compiler specs + design decisions
    ├── design/                      24 completed design explorations
    ├── milestones/                  Completed milestone plans (M0–M8)
    └── test-consolidation/          Completed test consolidation work

.working/                            Working docs (gitignored, not checked in)
├── *.md                             Active design explorations
└── archive/                         Completed working docs

Working Documents Convention

Active design explorations and scratch documents live in .working/ at the project root (gitignored — not checked in). This keeps the committed docs/ directory clean and authoritative.

Lifecycle:

Create a working document in .working/ for design exploration
When the exploration is complete, uplift the relevant findings into the appropriate docs/ chapter
Archive the working document by moving it to .working/archive/

Key rule: .working/ documents are never the source of truth. If something is decided, it must be reflected in the docs/ chapter files. Working documents are disposable scratchpads.

Contributing

Update chapter files when architectural decisions or constraints change
Add new ADRs by copying decisions/template.md to a new numbered file
Use .working/ for design explorations (not checked in)
Uplift findings from .working/ into chapters when done, then archive the working doc
Update this README if chapters are added or reorganized