import type { Section } from "#types/document.types";
import { TOOL_SECTION_ICON } from "#configuration/icons/build.icons";
import { TOOL_SECTION_ID } from "#core/ids/build.ids";

const GAP_DIAGRAM =
    'flowchart TB\n    gap["A capability gap appears"]\n    owner{"Does something already own this concern?"}\n    extend["Extend the owner, so the next consumer inherits it"]\n    build["Author a tool with a command surface, in the tree"]\n    loop["A manual loop"]\n    workaround["A workaround"]\n    gap --> owner\n    owner -- yes --> extend\n    owner -- no --> build\n    gap -. the tempting moves .-> loop\n    gap -. the tempting moves .-> workaround';

const LOOK_DIAGRAM =
    'flowchart TB\n    question["A visual question"]\n    tool["The look tool · one capture per question"]\n    shot["The screenshot · what a person sees"]\n    console["The console log · what the page said while rendering"]\n    layout["The layout · what the engine computed"]\n    dom["The markup · what was actually in the tree"]\n    answer["An answer with a value someone can read"]\n    question --> tool\n    tool --> shot\n    tool --> console\n    tool --> layout\n    tool --> dom\n    shot --> answer\n    console --> answer\n    layout --> answer\n    dom --> answer';

const DESTRUCTIVE_DIAGRAM =
    'flowchart TB\n    invoke["An irreversible operation is about to run"]\n    preconditions["Enumerate the standing preconditions bearing on it"]\n    code["Read the tool\'s code for each · not its help"]\n    missing{"Does the tool implement every one?"}\n    hand["Take the missing step by hand first, and declare it"]\n    encode["Encode the step in the tool for the next invocation"]\n    run["Run it"]\n    invoke --> preconditions --> code --> missing\n    missing -- yes --> run\n    missing -- no --> hand --> encode --> run';

const TOOL_SECTION: Section = {
    icon: TOOL_SECTION_ICON,
    id: TOOL_SECTION_ID,
    intro: "A capability gap is closed by a tool that lives in the tree with a command surface of its own, as <cite>closing a gap</cite> draws, which is how the stance's manual-step sentence is held by something other than a person. Which tools exist, what kind each one is, and why it exists follow from the method rather than from preference: a tool exists where a check needs an input, a person would otherwise repeat a step, or an eye would otherwise stand in for a measurement, as <cite>a look tool</cite> shows. An irreversible one reads its preconditions first, as <cite>before an irreversible tool</cite> draws. Semantic operations on the grammar page states the caller's half of the same contract: an instruction names an operation, and the binding names the tool.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Close a gap by authoring a tool with a declared command surface that lives in the tree. Give the tool a contract a reader sees before any effect: its flags declared, an undeclared flag refused, its help printed on request. Let a tool that allocates or rewrites values run in preview and show its diff before it applies. Where a mechanism requires a write to a surface, make that surface tool-writable before the requirement exists.",
                    boundary:
                        "A one-off script belongs in a scratch location and is promoted into the tree the moment its reusability appears. The discipline is for anything a second run will need, and a scratch tool that gets a second run has already crossed that line.",
                    cause: "A manual loop is faster the first time and slower every time after, and nothing records how it was done.",
                    decision: "Extend the tool that already owns the concern before authoring a second one.",
                    failureMode:
                        "A ten-minute manual procedure runs weekly for a year, differently each time, and the one week it is skipped is the week it mattered.",
                    kind: "lesson",
                    principle:
                        "A capability gap is closed by a tool in the tree, never by a manual loop or a workaround.",
                    problem:
                        "The cheapest response to a missing capability is to do the thing by hand, and by hand is where the variance lives.",
                    validation:
                        "List every step you performed by hand this week. Each one is either a tool that does not exist yet or a tool that exists and was not used.",
                },
                {
                    kind: "text",
                    text: "The tools fall into kinds by what they stand in for. A generator stands in for a fact that would otherwise be typed by hand: an index, a catalogue, a document derived from a manifest, a rendered diagram, which is derived state written by code. A validator stands in for a review that would otherwise be performed from memory: discovery of every route, leaks of internal names into public copy, the resolution of every reference a document makes. A fixer stands in for a repair that has one correct answer. A probe stands in for an eye. Each kind is reached through one chain, for the reason one chain gives.",
                },
                {
                    kind: "text",
                    text: "The probe is the kind worth dwelling on, because the eye is the measurement most often trusted and least often right, the failure it looked right names. A visual, numeric or timing defect is diagnosed by adding a probe that writes a value you can read before changing anything, observability built for the one question, and by binary-searching the pipeline against a known-good control. Adjusting values across repeated runs proves nothing. So a look tool returns what the eye cannot: beside the screenshot, the console log the page produced while rendering, the layout the engine computed, and the markup that was actually in the tree. A screenshot the person hands over is the measurement, and the tool takes one capture per question, never a loop of relaunches, because the second capture is the tuning-by-eye the probe exists to replace.",
                },
                {
                    kind: "text",
                    text: "A tool that performs an irreversible operation performs it without any standing precondition its code does not implement, and it reports success. So before such a tool runs, the standing instructions bearing on that operation are read against what the tool does, its code rather than its help, since a precondition it does not implement is one its help has no reason to mention. A missing step is taken by hand first and declared, then encoded in the tool so the next invocation does not depend on whoever remembers. A tool omitting a step before a deletion closes nothing later, because the operand is gone.",
                },
                {
                    kind: "text",
                    text: "The mandate and the write path arrive in different changes, and only the mandate feels like the work. A mechanism is built, it needs an operand, the operand lives in a file, and nothing in building the mechanism asks how that file gets written. The requirement lands complete and the write it depends on is left to whoever hits it, by hand, with none of the protections a tool write carries. So the question what writes this is asked the moment a surface becomes an operand, and the answer is a tool path before the mandate that needs it.",
                },
                { caption: "closing a gap", kind: "mermaid", text: GAP_DIAGRAM },
                { caption: "a look tool", kind: "mermaid", text: LOOK_DIAGRAM },
                { caption: "before an irreversible tool", kind: "mermaid", text: DESTRUCTIVE_DIAGRAM },
            ],
            title: "Every manual step is a missing tool",
        },
    ],
    title: "Tools live in the tree",
};

export const TOOL_SECTIONS: readonly Section[] = [TOOL_SECTION];