43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
# Schema Runtime and Publication Agent Guide
|
|
|
|
This file applies to `internal/cli/`. Read
|
|
[`docs/schema-contributor-guide.md`](../../docs/schema-contributor-guide.md)
|
|
before editing.
|
|
|
|
## Owning inputs
|
|
|
|
| Change | Edit |
|
|
|---|---|
|
|
| Canonical identity, primary path, aliases, navigation | `schema_command_registry.json` |
|
|
| Parameter/property mapping | `schema_parameter_bindings.json` or reviewed metadata overlay |
|
|
| Safety, interface, runtime gate | `schema_hints/metadata/<product>.json` |
|
|
| Agent selection and examples | `schema_hints/selection/<product>.json` |
|
|
| Exact reviewed omission | `schema_command_exclusions.json` |
|
|
| Runtime query/projection behavior | Go implementation and focused tests in this package |
|
|
|
|
The executable Cobra tree outside this package owns whether a command exists
|
|
and which flags it accepts. Do not create a command or flag in Schema inputs.
|
|
|
|
## Generated boundary
|
|
|
|
- `schema_catalog.json` and `schema_agent_metadata/` are generated outputs.
|
|
- Never hand-edit, merge from, or use a previous generated output as an input.
|
|
- Change the owning reviewed input or generator, run `make generate-schema`,
|
|
and inspect authored and generated diffs separately.
|
|
- A broad unrelated generated diff is a failure signal, not acceptable churn.
|
|
|
|
## Self-check
|
|
|
|
- Every public runnable Cobra leaf is bound or has one exact reviewed
|
|
exclusion; every delivered tool binds back to a runnable leaf.
|
|
- Registry identity and native annotations agree; aliases do not mutate the
|
|
resolved contract.
|
|
- Parameters reference real flags and retain Cobra-required floors.
|
|
- Selection examples use executable paths/flags and never include `--yes`.
|
|
- Runtime confirmation gates and published safety metadata agree.
|
|
- Full, compact, summary, alias, and Catalog projections derive from the same
|
|
typed `ToolSpec` and preserve provenance winners.
|
|
|
|
Run the focused package/generator tests and the complete command list in
|
|
`docs/schema-contributor-guide.md`, beginning with `make generate-schema`.
|