Dokumentasi FormSpec

FormSpec adalah platform spec-driven: aplikasi dideklarasikan sebagai kumpulan spec YAML (workspace → app → module → kinds), lalu diinterpretasikan saat runtime oleh engine dan renderer resmi. Prinsip yang mengikat seluruh dokumentasi ini:

Spec adalah kontrak; renderer adalah implementasi kontrak itu.

Karena itu dokumentasi terbagi dua poros utama — spec/ (kontrak, normatif) dan renderers/ (implementasi resmi, deskriptif) — ditambah section pendukung.

Peta Dokumen

Section	Isi	Sifat
spec/platform/	Kontrak lintas sisi: overview, workspace/app/module, kind system, control plane, plane protocol, datastore, marketplace	Normatif, semver
spec/backend/	Kontrak data & perilaku: core basic/extended, entity extension, PersistBackend	Normatif, semver
spec/frontend/	Kontrak visual: hirarki Shell→App→Page→Component, VisualSpecKind, Renderer, Spec Resolution API, katalog kind per tier, FormSpecExpr	Normatif, semver
renderers/shadcn-shell/	Frontend renderer resmi (React + shadcn/ui)	Deskriptif, dated
renderers/jsonb-persist/	Backend renderer resmi (PersistBackend hybrid JSONB, Postgres/SQLite)	Deskriptif, dated
architecture/	Topologi deployment, HA/failover, K8s operator, admin surfaces, struktur repo	Deskriptif
runtimes/	Internals per komponen runtime: formspec-ctl, formspec-resource, formspec-operator, formspec-sidecar, engine API layer	Deskriptif
cli-tools/	Referensi CLI: formspec, formspec-ctl, formspec dev, formspec generate, formspec consult	Deskriptif
registry/	FormSpec Module Registry: konsep, quickstart publish/install, CLI reference, REST API, self-hosting, trust tier	Deskriptif
ai/	FormSpec AI: formspec-consult, formspec-local-mcp/formspec-remote-mcp, LLM provider layer (Vercel AI SDK, BYOK), FormSpec Skill	Deskriptif — design, belum diimplementasikan
guides/	Cara menjalankan, tutorial Order-to-Cash, panduan menulis renderer/shell/persist-backend, checklist maintainer (schema & rilis)	Tutorial
reference/	Glossary istilah kanonik, referensi ringkas 9 ctx.* primitives & 3-level registry	Referensi
comparison/	FormSpec dibandingkan platform lain	Referensi

Catatan: dokumen kerja & sejarah (plan, changelog, presentations, technical-notes) tidak ada di sini — semuanya di docs_internal/ di root repo, dan tidak masuk docs-site.

Jalur Baca per Persona

App developer (membangun aplikasi di atas FormSpec): spec/platform/01-overview → spec/platform/02-workspace-app-module → spec/backend/01-core-basic → spec/frontend/06-page-kinds → guides/order-to-cash-tutorial.

Renderer/Shell author (menambah renderer visual atau persist backend baru): spec/frontend/01-visual-hierarchy → 02-visual-spec-kind → 03-renderer-kind → 04-spec-resolution-api → guides/authoring-a-page-renderer (atau spec/backend/04-persist-backend → guides/authoring-a-persist-backend).

Platform operator (menjalankan FormSpec untuk banyak workspace): architecture/01-architecture-overview → runtimes/ → cli-tools/04-formspec-ctl.

Framework contributor (mengubah kode FormSpec sendiri — cmd/, internal/, pkg/, renderers/react-shadcn/, sdk/): architecture/08-repo-structure → dokumen spec/ atau renderers/ yang relevan dengan area yang disentuh → guides/maintainer-checklist (regenerate artefak schema saat pkg/spec berubah, dan prosedur rilis CLI).

Konvensi

• Direktori tanpa nomor; file berprefix dua digit sesuai urutan baca; README.md per direktori adalah indeksnya.
• Dokumen kontrak (spec/) memakai header Version (semver) + Status (Outline → Draft → Final). Dokumen implementasi (renderers/, runtimes/) memakai Updated: (tanggal).
• Bahasa dokumen: Indonesia; nama kind, field, dan istilah teknis tetap English.
• Seluruh isi ditulis present-tense — dokumen ini menjelaskan FormSpec sebagaimana adanya, bukan sejarah perubahannya.