docs(P21): restructure docs/ into Jekyll Pages site (REQ-54, REQ-55, REQ-56)

---ci--- project: acdl phase: 21 milestone: v1.6 status: execute ---/ci--- Restructure docs/ into a Jekyll-style GitHub Pages site: - docs/_config.yml (Pages config + nav, excludes internal/) - docs/index.md (landing: platform + consumer model, Features, Roadmap) - docs/modules/index.md (catalog: primitives + modules, normalized terms) - docs/contracts/index.md (schema, fields, sample, multi-contract) - docs/pipeline/index.md (CI + deploy pipeline, stages mermaid, streaming) - docs/pipeline/versioning.md (module + deploy-pipeline versioning) - docs/environments/index.md (platform-managed envs + onboarding, REQ-61) - docs/consumer-guide.md (renamed from CONSUMER_GUIDE.md; GitHub-only, no .gitea, forge->platform runners, L2->modules, composition->pattern, updated mermaid with security-checks + infrastructure-apply) - docs/architecture.md (consolidated from architecture.md + architecture-v1.0.md, current-architecture only, normalized terms: primitives/modules, platform runners, no L1/L2/forge/gitea in prose) - Removed docs/architecture-v1.0.md (consolidated) + docs/CONSUMER_GUIDE.md (renamed). No .ciagent/ or .gitea/ references in docs/. Consumer-facing terminology normalized (L2->modules, L1->primitives, composition->pattern, forge-> platform runners).
2026-07-22 18:22:58 +00:00
parent b758a7c242
commit d830357230
11 changed files with 954 additions and 1223 deletions
@@ -0,0 +1,63 @@
+# Contracts
+
+A consumer declares intent in a **contract** — a small YAML file that
+references the central deploy pipeline, names a module, selects an
+environment, and supplies module-specific inputs. The platform validates,
+resolves, and deploys it.
+
+## The contract file
+
+A consumer repo keeps its contract at `.acdl/contract.yaml`. A minimal
+example (the `static-asset` module):
+
+```yaml
+uses: acdl/pipelines/deploy.yaml@v1.4
+module: static-asset
+environment: dev
+inputs:
+  bucket_name: my-static-site-assets
+  region: us-east-1
+```
+
+A `microservice` example:
+
+```yaml
+uses: acdl/pipelines/deploy.yaml@v1.4
+module: microservice
+environment: dev
+inputs:
+  image: my-registry/my-microservice:latest
+  port: 8080
+  env:
+    LOG_LEVEL: info
+```
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `uses` | string | yes | Reference to the central deploy pipeline, **versioned** with a floating MAJOR+MINOR tag (e.g. `acdl/pipelines/deploy.yaml@v1.4`). Bare or `@main` references are discouraged. See [Versioning](../pipeline/versioning). |
+| `module` | string | yes | Module name from the registry — any primitive or module (e.g. `static-asset`, `microservice`, `s3`). See the [module catalog](../modules/). |
+| `environment` | string | yes | The platform-managed environment to deploy to (e.g. `dev`). See [Environments](../environments/). |
+| `inputs` | object | yes | Module-specific inputs (see the module's README). |
+
+## Validation
+
+The contract is validated against
+[`schemas/contract.schema.json`](https://github.com/acdl/acdl/blob/main/schemas/contract.schema.json).
+An invalid contract (missing field, unknown module, wrong type) fails at the
+validate-contract stage with a clear error.
+
+## Sample contract
+
+The reference example is
+[`contracts/static-asset.yaml`](https://github.com/acdl/acdl/blob/main/contracts/static-asset.yaml),
+which uses `@v1.4` as the canonical versioned `uses:` reference.
+
+## Multiple contracts
+
+A consumer repo may contain more than one contract (e.g. one per service or
+one per environment). Each contract is a separate deployment; each is
+referenced by a CI definition in `.github/workflows/` that invokes the
+central reusable workflow with the contract path. See the
+[Consumer Guide](../consumer-guide/) for the multi-contract pattern.