Reference
What the reference section will hold, from the hyper command tree to error codes and legacy aliases, and why only qualified entries become executable reference.
On this page
The reference is where you will look up an exact command, setting, error or word and find its meaning, the permission it needs and what it does. This page lists what the section will hold, the rule that decides when an entry becomes something you can run, and what you can read now.
The reference will cover ten areas #
Reference facts are to come from the product's reviewed, versioned contracts and be generated from them, not written separately by hand.
| Area | What it will hold | Standing |
|---|---|---|
| Commands | The hyper command tree, grouped into families, with each command's action, effect and the component that presents it | Planned |
| Trusted composer | How the !hyper prefix is recognized in Rocket! and Lanes composers, and which text never runs | Planned |
| Actions | Each action's stable identity, inputs, results, effect and the owner that admits it | Planned |
| Options and output | Scope options, output for people and for scripts, waiting and non-interactive behavior | Planned |
| Exit codes | What each exit status means, including refusals and outcomes nobody could confirm | Planned |
| Settings and schemas | Each registered setting with its key, default, scope and owning component, and the schemas of public records | Planned |
| Error catalog | Each typed refusal with its cause, whether a retry is safe and the repair | Planned |
| Protocol compatibility | Which versioned protocols and package formats a release supports, and which interfaces are internal | Planned |
| Glossary | The product's words, and historical names that still point to something real | Planned |
| Standings | What each standing means and what counts as evidence for it | Planned |
Only qualified entries become executable reference #
An entry becomes executable reference only when a qualification receipt exists for that exact release, target and profile. Then the entry can show exact syntax, defaults, examples, the grant it needs, its refusals and its exit details. Copy buttons appear only on pages whose standing is Qualified.
Until then:
- an entry appears as a Planned description, with no command to copy;
- an entry that exists only in the command registry, or is internal to the product, stays out of executable reference;
- a known gap reads Unavailable and names the missing requirement, and missing evidence reads Unknown.
Source code, a passing CI run, a pull request or a registered command does not qualify an entry. Standings explains what does.
One command registry will feed the product and this reference #
Hypervibe plans one typed command registry: a single catalog of actions that every surface uses. Help text, shell completions, the Commands list (the searchable list of actions you can take where you are) and conformance tests are to be generated from it. The command reference here is to be generated from it too, then narrowed to the entries a release qualifies. There must never be a second, hand-edited list that could disagree with it.
A catalog entry alone enables nothing. At runtime the product is designed to tell an available action apart from one that is unavailable, unauthorized, stale or unsupported, and to name the missing implementation or version.
Settings follow the same rule with records of their own. No configuration file is meant to be edited by hand: a value is either a registered setting with an owner, a scope and a revision, or a managed file generated from those records.
Results will name the outcome, not just success or failure #
The design keeps apart outcomes that a single success flag would blur. Planned setup, for example, distinguishes seven outcomes, each with its own exit status, which Install lists.
| Outcome | What it tells a person or a script |
|---|---|
| Ready | Setup finished and its check passed |
| Usage error | The command line itself was not valid |
| Refused with nothing changed | Setup refused before making any change |
| Not confirmed yet | The last step was interrupted, so the outcome must be looked up, not assumed |
| Needs a decision | A person must decide before it continues |
| Not ready yet | Setup is waiting or repairing and will finish on its own |
| Refused after a change | It stopped after a recorded change, and the receipt lists what changed |
A command that only admits work is designed to say accepted, not completed. Errors will be typed, such as usage, policy, conflict and unavailable, and each will say whether to retry or to look up the original outcome first. A refusal will name its target, the reason, the responsible owner, how fresh its information is and the next useful action. It will never print a credential.
Where to go next #
- Commands describes the planned
hypercommand families and the trusted!hyperprefix. - Glossary defines the words used across these pages.
- Standings explains how a claim moves from Planned to Qualified.
- Architecture shows who owns each decision behind a command.
- Releases will list each public release and what it qualifies.