docs(skill): document the lifecycle and inference, and rewrite the guide - #35
Merged
Conversation
Two gaps a reader could not close from the shipped docs. The lifecycle was scattered across three pages and complete on none. Of the four managed deployment states the control plane reports, only `ready` was ever named; `working`, `needs_attention`, and `stopped` appeared nowhere, so an agent had no way to tell a busy Goal from a stalled one. The page states all four with their reasons, explains that Ready is scoped to an exact revision digest, and shows that `plan --session` is the form that produces a reviewable diff. It also records that `logs` truncates at 50 rows by default, which is the usual cause of an agent misreading a run. Model selection was undocumented despite being live. `--model` accepts exactly telos/default, telos/max, or <connection-name>/<model-name>, and resolves through $TELOS_MODEL and the stored `telos config --model` default before falling back to telos/default. The connection name is the user's own label, not the provider id — an easy thing to get wrong from the config output alone. Connecting a subscription has no CLI path at all, so the page tells the agent to stop and hand off to its user. Both are linked from SKILL.md; unlinked references do not render. Claude-Session: https://claude.ai/code/session_01SiadmMrEC3mALxqVG2SQze
The entry point opened on `## Install` and never said what Telos does, then gave five disconnected fragments — install, specify, apply, ready, local runs — with no command output anywhere in them. A reader could not tell success from failure because they had never been shown either, and the page linked to nothing, so it was a dead end into a seven-page set. It is now one Goal walked from nothing to a verified service, with output at every step, and it says outright that Telos writes the implementation. The frontmatter fields that decide where work runs and what it costs are called out rather than shown silently. `run` is introduced as the bounded alternative to `apply` instead of trailing after it, and the page ends by routing to the reference that answers the next question. The example spec omits `skills:` rather than showing a form that does not resolve; attaching skills and rubrics is left to its own reference. Claude-Session: https://claude.ai/code/session_01SiadmMrEC3mALxqVG2SQze
The reference pages render verbatim on the public docs site. Some of what they carried was not documentation but instructions to the agent about its own behaviour — "Avoid recursive fan-out", "Never treat successful submission as successful completion", "Do not silently pipe and execute a remote installer when the user only asked for advice". Those tell a reader nothing about what Telos can do, and they were the closing lines of two pages. Conduct now lives in SKILL.md's Guardrails, which the agent loads and the site does not render. Platform constraints stay in the references, restated as capability: a child cannot create a durable Goal, a child needs no credentials of its own because Telos scopes one for it, and a child takes the same bounds as any run. The cloud.md line duplicated a Guardrail and is simply dropped. Claude-Session: https://claude.ai/code/session_01SiadmMrEC3mALxqVG2SQze
rohangpta
force-pushed
the
codex/docs-cli-content
branch
from
August 31, 2026 04:01
83247bd to
df0bdf1
Compare
Local runs go through pi and nothing else: createAgentExecutor calls createPiExecutor with no alternative. The old wording read as though pi were one option among several. Claude-Session: https://claude.ai/code/session_01SiadmMrEC3mALxqVG2SQze
rohangpta
force-pushed
the
codex/docs-cli-content
branch
from
August 31, 2026 04:04
df0bdf1 to
3273c9c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reworks the Telos CLI documentation around one progressive model: author an observable contract, preview it, approve the resolved action, apply or run it, observe the exact revision, and retrieve the evidence or deliverable.
references/use-telos.mdfollows a reading-list service fromSPEC.mdthroughplan, approval,apply, route publication, live verification, revision, resumption, and deletion. Prose, commands, representative output, and interpretation stay adjacent.references/bounded-runs.mdgives local work its own spec, stopping bound, $20 default cost ceiling and override precedence, clean-checkout contract, isolated workspace semantics, and checkpoint-extraction flow.references/lifecycle.mdseparates Goal, spec, revision, session, deployment, and their state layers. It is authoritative for detailed status semantics, including public-route publication lag and compatibility-runtime provenance.references/glossary.mddefines Telos vocabulary in conceptual order, from Goal and spec through execution, evidence, and registry artifacts.run,apply,push, anddeleterequire approval of the resolved target and action. Cloud deletion is asynchronous and irreversible; local deletion preserves session history.references/goals.mdstarts with the smallest valid spec, then introduces the supported public fields and explains what a spec can express versus what the platform must already provide. Legacyextendsmachinery is not presented as a product surface.SKILL.mdowns the executable lifecycle and routes conditional detail into focused references instead of a wall of prohibitions.Documentation approach
The README is the style fixture for this work: one idea at a time, one evolving example, and reference material after the happy path. Agent-first means exact commands, stable vocabulary, observable outcomes, and explicit mutation boundaries. Human readers get the system model and capability boundary without having to reconstruct it from guardrails.
Generated IDs, digests, paths, and URLs in the worked transcript are labeled illustrative. Command and field shapes were checked against the current CLI and source; producing a real session-aware Cloud transcript still requires a live deployment.
Validation
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/telos-cligo test ./cmd/telos ./internal/cli ./internal/specgit diff --checkFollow-ups outside this PR
/docs/cli.telos configand command receipts.A Telos release publish and promotion is still required before these docs reach usetelos.ai/docs.