Repository navigation
feat(definitions): the overview is its author's markdown, and a read names what uses a definition - #287
Merged
Conversation
…es beside the document ## What this changes `create_definition` and `update_definition` take an optional `overview` beside `source`: Markdown for the person who runs the business, at least one character and at most 16,384 bytes in UTF-8, declared once as `OverviewField` and bounded the way `SourceField` is. The version keeps it as given in its content, every command and `get_definition` answer it as written, and `list_definitions` leaves it out. An update that leaves it out keeps the saved overview: the registry takes it from the saved version where it decides the update, so the same document with the same or no overview records nothing, and a new overview alone records a new version. The presenter of a definition's facts measures it as written. The argument's description is the sentence of the ask that fits the 300 characters an argument's description may hold on MCP; the two commands' descriptions add that it is written again with every update and that one left out stays. The instructions of a connection that may create a definition ask for it in the sentence that points to the formats, within the 2,000 characters a connection's instructions may hold. ## What goes `src/overview` and `src/overview-words` of `@on.auto/definitions`, `src/used-by/overview-at-read.ts`, the `overview` hook of a capability with `OverviewOf`, `OverviewContext`, `composedOverview` and `PreparedDefinition.overview`, each capability's `src/overview` folder and its golden files, the `about` of every function's front matter and a workflow's `document.metadata.about`, and `DefinitionSummary.about`. A description is one or two sentences for lists, so the rules of `src/document/written-texts.ts` go, with `src/markdown`, which only they read, and the positions the front matter kept for them. The Liquid reading of `@on.auto/definitions/template`, the shape words, a workflow's diagram and step words, the title its summary kept and the text and line a reasoning prompt kept go with the modules that read them, and so do the exports only those modules used. The words of a schema that a refused value is told in move to `src/schema-words`, as plain text. A workflow numbers its steps with the engine's one walk of its tasks, depth first and the body before the recovery, the same numbers as before. The users of a definition stay in `src/used-by`, with their own `NamedDefinition` shape. The loads measure saves every version with an overview at its bound. ## Tests The registry keeps the saved overview through an update that leaves it out, keeps none where none was saved, records a new version for a new overview alone and nothing for the same document and overview. The operations answer the overview as written, refuse an empty one and one past 16,384 bytes in UTF-8 whatever its length in characters, and keep it across an update that leaves it out. The schema words hold the cases they held, as plain text. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
## What this changes A definition that `get_definition`, `create_definition`, `update_definition` and `retire_definition` answer carries `used_by`: the active definitions of its playbook that use it, read from the playbook's registries when it is read. Each is its `type`, its `name` and its `relation`: `calls` for a workflow, with the `steps` that call it, each its `number` and its `name`; `sends-builds` or `asks-approval` for a prediction function whose trainer or approver it is; `remembers-runs` or `remembers-changes` for a recall function that folds its runs or its changes. It is left out when nothing uses the definition, and `list_definitions` does not carry it. What a workflow calls is not answered; its document says so. `DefinitionUserSchema` in `src/used-by/user-relations.ts` is the one shape of a user, a union of a call with its steps and of the other relations, and `DefinitionUser` derives from it, so the wire and `usersOf` hold the same relations. `answeredDefinition` loads the registries of the other types beside the one it read or wrote and fills `used_by` through `usersOf`. ## Tests The operations answer the active users of a definition in its playbook, each with its relation and a workflow with its steps, and leave out a retired user and one in another playbook; they leave `used_by` out where nothing uses a definition and in a listing, and answer it on create, update and retire alike. A server answers, over HTTP and as the MCP tool alike, an interaction function that a workflow calls in two steps, a prediction function sends builds to and two recall functions remember, one its runs and one its changes. The function used is an interaction function because the trainer and the approver a prediction function names are. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…s a definition ## What this changes Each of the six format references loses its `about` row, and its section The overview says what an author gives as `overview` beside the document, in the words of the field: Markdown for the person who runs the business, why the definition exists, what it does and how it fits, in one to three short paragraphs with a Mermaid diagram where a flow is worth a picture; that it is written after the document and again with every update, holds 1 character to 16,384 bytes in UTF-8, and stays as written until an update gives another. The workflow format keeps its advice to name each task for what it does, since `used_by` names the steps by their tasks. The terminology drops About and says what an overview is now, and a description is one or two sentences for lists. The HTTP and MCP references say what `overview` and `used_by` are, each relation of `used_by` with an example, that an overview changed alone makes a version, and that the instructions ask for an overview; the computation guide checks the overview the agent saved, and the output shapes leave the overview out. The READMEs of `@on.auto/definitions` and of the six capabilities say what is true now: the field and its bounds, the update that keeps a saved overview, `used_by` and its one schema, the words of a refused value in `src/schema-words`, the summary of a workflow and the numbers of its steps, and the layout of each package. The loads of a type are measured again with an overview at its bound in every version, and the sizes of the instructions and the listings on MCP are the ones their tests pin. The OpenAPI document, written again by `pnpm docs:openapi`, holds no change past the two commits before. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…hat stays The container workflow reads the initialize answer of the MCP endpoint for one sentence of the instructions, to see that they are served. It read the sentence that points to get_guide, which changes with what the instructions ask of an agent. It now reads the sentence that says what the runtime, Studio and the agent are, which every wording of the instructions keeps. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
rami-hatoum
pushed a commit
that referenced
this pull request
Oct 22, 2026
🤖 I have created a release *beep* *boop* --- ## [0.17.0](v0.16.0...v0.17.0) (2026-10-22) ### Features * **api:** the instructions and the playbook tools claim a request for a playbook ([#288](#288)) ([e4e6f86](e4e6f86)) * **connections:** a client names the scopes it may ask, and a way takes the one covering its scope ([#289](#289)) ([e05a127](e05a127)) * **connections:** a connect link names what its page cannot know, and the agent shows it as a link ([#290](#290)) ([8d1de91](8d1de91)) * **definitions:** the overview is its author's markdown, and a read names what uses a definition ([#287](#287)) ([7c1c637](7c1c637)) * **ledger:** a layout number, written at creation and checked at open, replaces the shape checks ([#281](#281)) ([a48be0e](a48be0e)) ### Bug Fixes * **operations:** a version 7 uuid made in the same millisecond as the last sorts after it ([#285](#285)) ([846a36d](846a36d)) * **prediction:** a model loads with the telemetry of onnxruntime off, so its process leaves nothing ([#283](#283)) ([ea1a6d8](ea1a6d8)) * **server:** the start's waits run on Effect's clock and the restart mark names its port ([#282](#282)) ([db6c858](db6c858)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: beonautobot[bot] <298957281+beonautobot[bot]@users.noreply.github.com>
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.
What this changes
A definition's overview is Markdown its author gives beside the document.
create_definitionandupdate_definitiontake an optionaloverview: Markdown for the person who runs the business, written from everything the author knows of them and of the playbook, on why the definition exists, what it does and how it fits, in one to three short paragraphs, with a Mermaid diagram in a fenced block where a flow is worth a picture. It holds 1 character to 16,384 bytes in UTF-8. Each version keeps it as written, andget_definition,create_definition,update_definitionandretire_definitionanswer it so;list_definitionsleaves it out. An update that leaves it out keeps the saved overview, the same document with the same or no overview records nothing, and a new overview alone records a new version. The instructions and the two commands ask the agent for it.The runtime composes nothing. The overview the runtime derived from a document goes: its data and writer, the words of every type, each capability's overview hook and golden files, the sections added at read, the
aboutof every function's front matter and of a workflow's metadata, and the rules that kept headings out of a description. A description is one or two sentences for lists. The words a refused value is told in stay, as plain text in their own folder; a workflow numbers its steps with the engine's one walk of its tasks.A read says which definitions use the definition. The four commands above answer
used_by: the active definitions of the playbook that use this one, read from the playbook's registries each time, each with itstype, itsnameand itsrelation:callsfor a workflow, with thestepsthat call it;sends-buildsorasks-approvalfor a prediction function;remembers-runsorremembers-changesfor a recall function. It is left out when nothing uses the definition, and the listing does not carry it.The six format references, the terminology page, the HTTP and MCP references, the package READMEs and the OpenAPI document say what is true now.
Tests
used_byon create, update and retire alike; a server answers the same over HTTP and as the MCP tool.Checklist
feat(reasoning): .... It becomes the squash commit and the changelog entry.pnpm checkpasses locally, with every file at 100% coverage.