docs(concepts): add schema-format.md + meta-schema.md

Graduates the internal `.agents/context/schema-spec.md` design brief into public, maintained user-facing documentation under `docs/concepts/`.

`schema-format.md` is the canonical reference for the `decree.schema.yaml` format — every top-level key, every field-level option, every constraint with the per-type compatibility matrix, the `dependentRequired` and `validations` cross-field rule mechanisms, the field-path and slug regexes, recommended `format:` values (advisory), import/export semantics, strict mode, and vendor extensions.

`meta-schema.md` documents the JSON Schema 2020-12 meta-schemas under `schemas/v0.1.0/`: what they cover (layer-1 structural validation) vs non-goals (layer-2 semantic rules stay Go-side), the URL scheme and SemVer stability policy, and how to wire them into editor tooling (yaml-language-server modeline), CI (`check-jsonschema`), and programmatic validators across languages.

Trims `schemas-and-fields.md` to be the higher-level concepts overview — lifecycle, drafts vs published versions, quick example, brief intros — with cross-links to the new full reference. Updates `getting-started.md` to use the canonical `decree.schema.yaml` filename and the `# yaml-language-server` modeline. Adds the new docs to `mkdocs.yml` nav and links them from `README.md` alongside the published meta-schema URLs. Fixes the orphaned anchor in `typed-values.md` to point at the moved Constraints section.

Closes #127.

Author: zeevdr

README.md

@@ -334,6 +334,11 @@ The API is defined in Protocol Buffers under [`proto/`](proto/), published to BS
 
 Values use a `TypedValue` oneof — integer, number, string, bool, timestamp, duration, url, json — with null support.
 
+The schema YAML format authors write to define their config shape is documented in [Schema Format](docs/concepts/schema-format.md). The corresponding [JSON Schema 2020-12 meta-schemas](docs/concepts/meta-schema.md) for editor IntelliSense and CI validation are published at:
+
+- `https://schemas.opendecree.io/schema/v0.1.0/decree-schema.json` — validates `*.decree.schema.yaml`
+- `https://schemas.opendecree.io/schema/v0.1.0/decree-config.json` — validates `*.decree.config.yaml`
+
 All endpoints that accept a tenant or schema ID also accept the **name slug** — the server resolves automatically. Use UUIDs or human-readable names interchangeably:
 
 Generate client stubs in any language from BSR, or use the official SDKs:

docs/concepts/meta-schema.md

@@ -0,0 +1,128 @@
+# Meta-schema
+
+The OpenDecree meta-schema is a [JSON Schema 2020-12](https://json-schema.org/draft/2020-12/schema) document that describes the [decree schema-format](schema-format.md) itself — what keys are valid, what types are allowed, what constraints belong with which field type. Tooling that consumes the meta-schema can validate `*.decree.schema.yaml` files offline without shelling out to the Go reference parser.
+
+> **Alpha Software** — OpenDecree is under active development. The schema format and meta-schema may change without notice between versions. Not recommended for production use yet.
+
+## What's covered
+
+The meta-schema enforces the **layer-1 structural shape** of a schema YAML:
+
+- Required keys (`spec_version`, `name`, `fields`).
+- Slug regex on `name` and field-path regex on `fields` map keys.
+- The 8 valid field types and the per-type constraint compatibility matrix (numeric / string / json / other).
+- Top-level reserved keys (`dependentRequired`, `validations`).
+- `unevaluatedProperties: false` at every object level — unknown keys are rejected.
+- `x-*` vendor extensions accepted at every object level.
+
+## What's not covered
+
+Layer-2 semantic rules that JSON Schema cannot express stay in the Go parser at [`internal/schema/validate_constraints.go`](https://github.com/opendecree/decree/blob/main/internal/schema/validate_constraints.go):
+
+- Referential integrity between `redirect_to` and existing field paths.
+- `dependentRequired` keys/values referring to defined fields (not just regex-valid paths).
+- `validations` entries referring to defined fields (the meta-schema only checks `rule`/`message` are non-empty; expression compilation and field-resolution come from the CEL engine).
+- Range sanity: `minimum > maximum`, `minLength > maxLength`, etc.
+- Prefix-overlap rejection between sibling field paths (e.g. `payments` and `payments.fee` cannot coexist).
+
+Runtime validation of config values against the schema is also out of scope — that is a separate concern handled in [`internal/validation/`](https://github.com/opendecree/decree/tree/main/internal/validation), driven by the per-field type and constraints.
+
+## Files
+
+The repository ships two single-file meta-schemas under [`schemas/v0.1.0/`](https://github.com/opendecree/decree/tree/main/schemas/v0.1.0):
+
+| File | Validates | Purpose |
+|------|-----------|---------|
+| `decree-schema.yaml` / `decree-schema.json` | `*.decree.schema.yaml` | Schema-definition format — fields, constraints, validations, dependentRequired. |
+| `decree-config.yaml` / `decree-config.json` | `*.decree.config.yaml` | Tenant-side config format — the values applied against a published schema. |
+
+YAML is the human-edited source of truth. JSON copies are generated by [`scripts/yaml-to-json.py`](https://github.com/opendecree/decree/blob/main/scripts/yaml-to-json.py) and committed alongside their YAML sources so consumers (schemastore.org, IDE language servers, CI validators) can `$ref` the JSON directly without a build step.
+
+## Using the meta-schema
+
+### Editor IntelliSense (yaml-language-server)
+
+Add the modeline on line 1 of your schema or config file. VS Code, Neovim, IntelliJ, Helix, and Zed via [yaml-language-server](https://github.com/redhat-developer/yaml-language-server) auto-apply the schema for autocompletion and inline error highlighting:
+
+```yaml
+# yaml-language-server: $schema=https://schemas.opendecree.io/schema/v0.1.0/decree-schema.json
+spec_version: v1
+name: payments
+fields:
+  payments.fee:
+    type: number
+```
+
+For config files:
+
+```yaml
+# yaml-language-server: $schema=https://schemas.opendecree.io/schema/v0.1.0/decree-config.json
+spec_version: v1
+values:
+  payments.fee:
+    value: 0.025
+```
+
+### CI validation
+
+Run [`check-jsonschema`](https://github.com/python-jsonschema/check-jsonschema) over your repo's schema files in CI:
+
+```bash
+pip install check-jsonschema
+check-jsonschema \
+  --schemafile https://schemas.opendecree.io/schema/v0.1.0/decree-schema.json \
+  '**/*.decree.schema.yaml'
+
+check-jsonschema \
+  --schemafile https://schemas.opendecree.io/schema/v0.1.0/decree-config.json \
+  '**/*.decree.config.yaml'
+```
+
+The decree project itself uses this approach via `make validate-meta-schemas` — see [`scripts/validate-meta-schemas.py`](https://github.com/opendecree/decree/blob/main/scripts/validate-meta-schemas.py).
+
+### Programmatic validation
+
+Any [JSON Schema 2020-12 validator](https://json-schema.org/implementations) can consume the meta-schema. Examples:
+
+- **Python** — [`jsonschema`](https://python-jsonschema.readthedocs.io/) (vanilla, what `validate-meta-schemas.py` uses)
+- **Node.js** — [`ajv`](https://ajv.js.org/) with the `ajv-formats` and `ajv-draft-2020` extensions
+- **Go** — [`santhosh-tekuri/jsonschema/v6`](https://github.com/santhosh-tekuri/jsonschema)
+- **Rust** — [`jsonschema`](https://crates.io/crates/jsonschema)
+
+## URL scheme + versioning
+
+```
+https://schemas.opendecree.io/schema/v{MAJOR}.{MINOR}.{PATCH}/decree-{schema|config}.json
+```
+
+**Pre-stable (current):** full SemVer in the path — `https://schemas.opendecree.io/schema/v0.1.0/...`. Each release of the meta-schema is published at its exact version path forever; older versions stay reachable for tools that pin a specific version.
+
+**Post-1.0.0 (future):** switch to major-only paths (`/v1/`) with permanent redirects from historical full-SemVer URLs. Matches the OpenAPI 3.x dated-URL practice.
+
+## Stability policy
+
+The meta-schema follows SemVer. Versions are bumped in a separate cadence from the decree server release; the meta-schema version is always present in the URL.
+
+| Change | Bump |
+|--------|------|
+| New optional property | Minor |
+| New `enum` value | Minor |
+| Loosening a constraint (higher `maxLength`, wider `pattern`) | Minor |
+| Removing a property | Major |
+| Removing an `enum` value | Major |
+| Tightening a constraint | Major |
+| Changing a property's type | Major |
+| Making an optional property required | Major |
+
+Per [project policy](https://github.com/opendecree/decree/blob/main/docs/development/checklists.md), the project is currently in alpha — both the schema format and the meta-schema may break without a major bump until v1.0.0. Until then, the version path makes it possible to pin against a known shape.
+
+## Local development
+
+The repository's `make validate-meta-schemas` target validates every checked-in `*.decree.schema.yaml` and `*.decree.config.yaml` against the matching meta-schema, plus a set of known-invalid fixtures under [`schemas/v0.1.0/testdata/invalid/`](https://github.com/opendecree/decree/tree/main/schemas/v0.1.0/testdata/invalid) that must fail validation. CI runs the same script on every PR.
+
+## Related
+
+- [Schema Format](schema-format.md) — the format reference the meta-schema describes.
+- [`.agents/context/schema-spec.md`](https://github.com/opendecree/decree/blob/main/.agents/context/schema-spec.md) — internal design brief for the v0.1.0 spec.
+- [JSON Schema 2020-12 spec](https://json-schema.org/draft/2020-12/schema)
+- [yaml-language-server modeline format](https://github.com/redhat-developer/yaml-language-server#using-inlined-schema)