feat(definitions): the overview is its author's markdown, and a read names what uses a definition

.github/workflows/ci.yml

@@ -694,7 +694,7 @@ jobs:
           grep --quiet '"isError":true' introspected.txt
           grep --quiet 'tool_server_not_configured' introspected.txt
           call_mcp /mcp '{"jsonrpc":"2.0","id":8,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"ci","version":"1"}}}' initialized.txt
-          grep --quiet 'Before writing a definition, read its format with get_guide' initialized.txt
+          grep --quiet 'Studio manages them; your agent is a separate client' initialized.txt
           call_mcp /mcp '{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"get_guide","arguments":{"guide":"reasoning-function"}}}' guide.txt
           grep --quiet '# Reasoning function format' guide.txt
           grep --quiet 'On this server, ' guide.txt

.oxfmtrc.json

@@ -12,8 +12,7 @@
     "pnpm-lock.yaml",
     "CHANGELOG.md",
     "packages/api/src/testing/openapi/openapi-3.1-schema-2022-10-07.json",
-    "docs/assets/openapi.json",
-    "**/*.overview.md"
+    "docs/assets/openapi.json"
   ],
   "overrides": [
     {

capabilities/computation/README.md

@@ -6,7 +6,7 @@ User documentation is [Computation function format](../../docs/reference/computa
 
 ## The document
 
-`parseComputationDocument(source)` reads a document with the shared reader of [`@on.auto/definitions/document`](../../packages/definitions/README.md#reading-function-documents) and gives a `ComputationFunctionDefinitionDocument`: an optional `description`, an optional `about`, which `AboutSchema` of `@on.auto/definitions/document` bounds and the summary carries into the overview, the `language`, `typescript`, the compiled `input.schema` and `output.schema` when the document has them, or for `output.shape` the [output shape](../../packages/definitions/README.md#output-shapes) it names with its schema compiled as `output.schema`, the `program`, the module, and the line it starts on. A language other than `typescript` is refused with the engine's `oneLanguage`, `The playbook's one language is TypeScript; write the program as a TypeScript function`, at its line. The front matter's keys are `description`, `about`, `language`, `input.schema`, `output.schema` and `output.shape`, the last two never together; every other key, `model`, `config`, `tools`, `output.format` and `input.default` among them, is an issue at its line, and the message for empty front matter names `the language`. A schema is compiled with the reader's compiler and validates values nested at most 512 levels.
+`parseComputationDocument(source)` reads a document with the shared reader of [`@on.auto/definitions/document`](../../packages/definitions/README.md#reading-function-documents) and gives a `ComputationFunctionDefinitionDocument`: an optional `description`, the `language`, `typescript`, the compiled `input.schema` and `output.schema` when the document has them, or for `output.shape` the [output shape](../../packages/definitions/README.md#output-shapes) it names with its schema compiled as `output.schema`, the `program`, the module, and the line it starts on. A language other than `typescript` is refused with the engine's `oneLanguage`, `The playbook's one language is TypeScript; write the program as a TypeScript function`, at its line. The front matter's keys are `description`, `language`, `input.schema`, `output.schema` and `output.shape`, the last two never together; every other key, `model`, `config`, `tools`, `output.format` and `input.default` among them, is an issue at its line, and the message for empty front matter names `the language`. A schema is compiled with the reader's compiler and validates values nested at most 512 levels.
 
 Parsing keeps the module as it is written. The module is checked when the document is saved, by the capability's `check` (`src/document/document-check.ts`), which asks the pool's check worker of [`@on.auto/definitions`](../../packages/definitions/README.md#the-check-at-save), a step of the save beside `prepare`, against `Input` and `Output`, the schemas as types, with the TypeScript compiler and the sandbox's own library, each problem refused with its line in the document and the compiler's words, in the words of a document that does not parse; a check that a ready checker does not finish within 2 seconds leaves the document unsaved, `invalid_input`, and a save that finds no checker ready is `unavailable`. A run never checks again.
 
@@ -65,4 +65,4 @@ A checkpoint counts the engine's own steps, so a loop whose body is one native o
 
 ## Source
 
-`src/index.ts` is the entry point and `src/testing/index.ts` the entry point of the test support. `src/document` holds the document: its type, the front matter's keys and parsing. `src/run` holds a run: its bounds, the input's checks, the call of the pool and the endings. `src/capability` holds the capability, whose guide is the public reference page, served to agents as `computation-function`. `src/overview` is the function's overview, told as what happens by the rules of [Told as what happens](../../packages/definitions/README.md#told-as-what-happens): one sentence, `computedSentence` of `@on.auto/definitions`, of what it is given and what it answers with, each field by its meaning, or the shape it answers, and under Details the tables of its input and its output and its program's language, through `inputDetails`, `outputDetails` and `programSection`. `reference-example.overview.md` is the overview of the example of the public reference page, `shaped-example.overview.md` that of the computation function of the reference of output shapes, and `month-window.overview.md` that of a function a workflow calls, as a read writes it with the workflow, which `computation-overview.test.ts` writes again and compares byte for byte. `src/testing` holds the example and what the tests share.
+`src/index.ts` is the entry point and `src/testing/index.ts` the entry point of the test support. `src/document` holds the document: its type, the front matter's keys and parsing. `src/run` holds a run: its bounds, the input's checks, the call of the pool and the endings. `src/capability` holds the capability, whose guide is the public reference page, served to agents as `computation-function`. `src/testing` holds the example and what the tests share.

capabilities/computation/src/capability/computation-function.test.ts

@@ -166,7 +166,7 @@ describe('a computation function definition that is refused', () => {
         {
           pointer: '',
           detail:
-            'Line 3, /model: model is not a key of the front matter; it takes description, about, language, input, output',
+            'Line 3, /model: model is not a key of the front matter; it takes description, language, input, output',
         },
         { pointer: '', detail: 'Line 5: The definition has no program: write it after the front matter' },
       ],

capabilities/computation/src/capability/computation-function.ts

@@ -14,7 +14,6 @@ import { Effect, Result } from 'effect';
 import type { ComputationFunctionDefinitionDocument } from '../document/computation-document.ts';
 import { documentCheck, invalidDefinition } from '../document/document-check.ts';
 import { parseComputationDocument } from '../document/document-parsing.ts';
-import { computationOverview } from '../overview/computation-overview.ts';
 import { computationRun } from '../run/computation-run.ts';
 import { computationBounds } from '../run/run-bounds.ts';
 
@@ -32,10 +31,9 @@ function parse(source: string): Effect.Effect<ComputationFunctionDefinitionDocum
   });
 }
 
-function summarize({ description, about, input, output }: ComputationFunctionDefinitionDocument): DefinitionSummary {
+function summarize({ description, input, output }: ComputationFunctionDefinitionDocument): DefinitionSummary {
   return {
     ...(description === undefined ? {} : { description }),
-    ...(about === undefined ? {} : { about }),
     ...(input.schema === undefined ? {} : { inputSchema: input.schema.document }),
     ...publishedOutputOf({ schema: output.schema?.document, shape: output.shape }),
   };
@@ -58,7 +56,6 @@ export function makeComputationFunctionAdapter({
     parse,
     check: documentCheck(pool),
     summarize,
-    overview: computationOverview,
     run: (document, input, _run, stripped) => run(document, input, stripped),
     longestAnyRunMs: deadlineMs,
   });

capabilities/computation/src/document/computation-document.ts

@@ -7,7 +7,6 @@ export interface OutputContract extends ValueContract {
 
 export interface ComputationFunctionDefinitionDocument {
   readonly description?: string;
-  readonly about?: string;
   readonly language: 'typescript';
   readonly input: ValueContract;
   readonly output: OutputContract;

capabilities/computation/src/document/document-parsing.test.ts

@@ -91,9 +91,9 @@ describe('the front matter of a computation function definition', () => {
         ),
       ),
     ).toEqual([
-      'Line 3, /model: model is not a key of the front matter; it takes description, about, language, input, output',
-      'Line 4, /config: config is not a key of the front matter; it takes description, about, language, input, output',
-      'Line 5, /tools: tools is not a key of the front matter; it takes description, about, language, input, output',
+      'Line 3, /model: model is not a key of the front matter; it takes description, language, input, output',
+      'Line 4, /config: config is not a key of the front matter; it takes description, language, input, output',
+      'Line 5, /tools: tools is not a key of the front matter; it takes description, language, input, output',
       'Line 6, /input/default: default is not a key of input; it takes schema',
       'Line 7, /output/format: format is not a key of output; it takes schema, shape',
     ]);
@@ -118,7 +118,7 @@ describe('the values in the front matter of a computation function definition',
 
   it('is checked with the program, whose issues it reports beside its own', () => {
     expect(issuesIn(programDocument('  ', 'language: typescript\nsize: 2'))).toEqual([
-      'Line 3, /size: size is not a key of the front matter; it takes description, about, language, input, output',
+      'Line 3, /size: size is not a key of the front matter; it takes description, language, input, output',
       'Line 5: The definition has no program: write it after the front matter',
     ]);
     expect(issuesIn('---\nlanguage: [typescript\n---\n')).toEqual([
@@ -141,23 +141,3 @@ describe('the program of a computation function definition', () => {
     ).toBe('export default function (input: Input): Output {\n  return input.perod;\n}');
   });
 });
-
-describe('the about of a computation function definition', () => {
-  it('is kept as its author wrote it', () => {
-    const frontMatter = 'language: typescript\nabout: |\n  The finance team reads it.';
-
-    expect(parsed(programDocument(functionOf('return input;'), frontMatter)).about).toBe(
-      'The finance team reads it.\n',
-    );
-  });
-
-  it('takes no heading, nor does the description, each refused at its line', () => {
-    const frontMatter =
-      "language: typescript\ndescription: '# Adds one'\nabout: |\n  The finance team reads it.\n  ---";
-
-    expect(issuesIn(programDocument(functionOf('return input;'), frontMatter))).toEqual([
-      'Line 3, /description: description takes no heading, since an overview writes its own: the line that begins “# Adds one” makes one, with # before its words or as a line of = or - under the words above it',
-      'Line 6, /about: about takes no heading, since an overview writes its own: this line makes one, with # before its words or as a line of = or - under the words above it',
-    ]);
-  });
-});

capabilities/computation/src/document/document-parsing.ts

@@ -86,7 +86,7 @@ function documentFrom(
   if (issues.length > 0 || Result.isFailure(decoded)) {
     return Result.fail([...issues, ...issuesOf(program)]);
   }
-  const { description, about, input, output } = decoded.success;
+  const { description, input, output } = decoded.success;
   const parts = {
     language: languageOf(decoded.success.language, lines),
     input: contractOf(input, 'input', lines),
@@ -103,7 +103,6 @@ function documentFrom(
     ? Result.fail(found)
     : Result.map(Result.all(parts), (checked) => ({
         ...(description === undefined ? {} : { description }),
-        ...(about === undefined ? {} : { about }),
         language: checked.language,
         input: checked.input,
         output: checked.output,

capabilities/computation/src/document/front-matter.ts

@@ -1,9 +1,4 @@
-import {
-  AboutSchema,
-  DescriptionSchema,
-  type FrontMatterSection,
-  type FrontMatterShape,
-} from '@on.auto/definitions/document';
+import { DescriptionSchema, type FrontMatterSection, type FrontMatterShape } from '@on.auto/definitions/document';
 import { Schema } from 'effect';
 
 const SectionSchema = Schema.Struct({ schema: Schema.optionalKey(Schema.JsonObject) });
@@ -15,7 +10,6 @@ const OutputSectionSchema = Schema.Struct({
 
 const FrontMatterSchema = Schema.Struct({
   description: Schema.optionalKey(DescriptionSchema),
-  about: Schema.optionalKey(AboutSchema),
   language: Schema.String,
   input: Schema.optionalKey(SectionSchema),
   output: Schema.optionalKey(OutputSectionSchema),