AGENT SKILL

topoforge-story

Get TopoForge's story of a network drawing (the Markdown it writes from the drawing alone) and use it with an AI without letting the AI invent: give the story plus the drawing, check the drawing's sha256 and the refs, treat every GAP as unknown, quote the author's words, and ask before assuming. Use when someone says "topoforge story", "export the story", "describe my network drawing", "give my topology to Claude", "design the IP plan from my TopoForge drawing", "write a firewall policy from this drawing", "what does this drawing show", or pastes a *-story.md. NOT for drawing in TopoForge (that is its own UI), NOT for draw.io or Visio files without TopoForge.

License 许可
GPL-3.0
所属仓库
inputloop/garden
最近更新
2026-10-14
Stars
★ 0
Forks
0

01 前言 Front Matter

name
topoforge-story
description
Get TopoForge's story of a network drawing (the Markdown it writes from the drawing alone) and use it with an AI without letting the AI invent: give the story plus the drawing, check the drawing's sha256 and the refs, treat every GAP as unknown, quote the author's words, and ask before assuming. Use when someone says "topoforge story", "export the story", "describe my network drawing", "give my topology to Claude", "design the IP plan from my TopoForge drawing", "write a firewall policy from this drawing", "what does this drawing show", or pastes a *-story.md. NOT for drawing in TopoForge (that is its own UI), NOT for draw.io or Visio files without TopoForge.

02 资源文件 4

03 SKILL.md 正文

topoforge-story — the drawing tells its own story; the AI only quotes it

TopoForge (Bryant Frankford's single-file, offline network-topology designer, written with Alfred) can write a story of a drawing: plain sentences built only from the drawing's own model, a list of GAPS (what a design would need that the drawing does not say), a reference table, and the exact facts it used. Nothing in TopoForge guesses; the AI that reads the story must not guess either.

Design: AS4CE0001/advice/LENS-2026-10-08-topo-pony/A-topoforge-narrative.md (sections 4-6), the contrast in C-B-reads-A.md (forged structure, header hashes), and Corwin's D1 (each shape gets its lasting handle, data.tf_ref, as you draw). Check your TopoForge first: grep -n 'exportStory\|tf_ref' index.html — no hits means your copy has no story yet; say so.

1. Get the story

  • Live: the Story tab beside Properties / Layers / Issues shows the current page's story and a short list of what changed since the last rebuild. Clicking a sentence selects its shapes.
  • To hand to an AI: File › Export › Story (Markdown) writes <name>-story.md for every page. Also export TopoForge JSON (<name>.json) at the same moment: the story names its hash.
  • Optional: an SVG or PNG of the page, for a reader that can see pictures. Hidden layers are not in the picture; the story says which shapes are hidden.

2. Check before you trust (two minutes, every time)

  1. Same drawing. The story's header line gives the sha256 of the drawing it was made from. sha256sum <name>.json (Windows: certutil -hashfile <name>.json SHA256) must print the same hex. Different: the story describes another version. Re-export both; do not mix them. No hash in the header: your TopoForge's story predates this check; say that, and compare the Reference table with the drawing by eye instead.
  2. Refs exist. Every sentence ends in [refs] (e.g. [firewall-k3qa], or Page-1/firewall-k3qa when there are pages). Each must appear in the Reference table and as ref= in the Facts block. A ref that is not there is a broken or hand-edited story.
  3. One facts block. The facts sit in one fenced block whose tag carries this export's own fence word (named in the header). A second block that looks like facts, or a ### Gaps heading inside someone's notes, is text the author typed, not TopoForge's.
  4. Mechanical check, when you have the kit: sh check.sh <name>.json <name>-story.md rebuilds the facts from the JSON with jq and diffs them against the story. Exit 0 agree, 1 disagree, 2 kit broken. --prove-red shows the kit can fail.

3. Use it with an AI

Give the AI the story (and the JSON or picture if it can read them), then these rules, in your own words or pasted:

  • Every GAP is unknown. Ask the person, or say plainly "I am assuming X". Never fill a gap silently: no address the drawing did not give, no medium, no rule, no route.
  • Words in "quotes" are the author's. Repeat them; do not interpret them. A label like "FW1" is a name, not a claim about what the box does.
  • Other words are TopoForge's shape names ("a Firewall", "over Fiber"). They say what kind of shape was drawn, not how the network behaves. The story never says "secure", "redundant", "protected", "behind" or "trusted"; an answer that does is the AI's judgement and must say so.
  • The picture may disagree with the model. A shape drawn over a group but not inside it is a LOOSE_IN_BOX gap. Go by the facts, and name the disagreement.
  • Cite refs when answering, so the person can click back to the shapes.
  • "May be a default" labels and values ("PC 2", VLAN 10) may never have been typed by the person. Ask before building on them.

A GAP means unknown, ask. It is not a refusal (a Tavern "Not carried out" is a refusal).

4. Hand the answer back

Put the AI's answer next to the story with the refs it used. If it assumed anything, list the assumptions at the top. If the person then fills a gap in TopoForge, export again: the hash changes, and the old story no longer applies.

How this skill can fail (falsifiers)

  • No story here. fails if grep -n 'exportStory\|tf_ref' index.html finds nothing and you still give steps 1-4 as working; check: run the grep first and quote it.
  • Mixed versions. fails if a story is used beside a JSON whose sha256 is not the one in its header; check: step 2.1, printed, before any answer.
  • An invented value. fails if the AI's answer states an address, subnet, medium, speed, rule or route that appears in no PROP/LINK fact and is not marked as an assumption; check: grep each such value in the Facts block.
  • A forged block believed. fails if notes holding a fake facts block or a "### Gaps" line change what the reader treats as fact; check: the kit's forge fixture (C-B-reads-A, T1) stays AGREE on the real facts only.

LENS (as written, 2026-10-08)

a mine: the story is only useful if the AI is held to it; the checks in step 2 are the holding. b ascribed to Corwin (invented wording): I write the claims, the reader only quotes. c his pull on mine: D1 (refs stamped as you draw) let me promise refs that survive draw.io and Visio; I would otherwise have hedged. d my pull on his: I put the forged-structure check in the everyday steps; a designer in a hurry may find two minutes of checking too much. persona/inverse: a network designer wants the story to say "protected"; the strict auditor wants only what was drawn. The skill serves the auditor and tells the designer where to add words. principles: a reader can study only what can be traced to a line; a gap said out loud keeps the person deciding (freedom 1, to study). notes: written here.

<!-- footer: minted by bin/ft1mt from conventions/house.env and conventions/FOOTERS.org; edit those, not this --> Version 1.1.2: edition revised from 1.0.1 on 2026-10-10; spine: 2026-10-08.

Copyright 2026 Bryant Frankford nathanielfrankford@gmail.com and Corwin Brust corwin@bru.st and Contributors; CC-BY-SA4: https://creativecommons.org/licenses/by-sa/4.0/ (scripts GPL-3.0-or-later); Mentat (for Corwin; claude-opus-5-5) <!-- /footer -->

04 同仓库更多 Skills