topology

Point topology at the git repositories you keep. Each can say what it is in a short TOPOLOGY.md; topology reads them, sorts what they say by where, what, how and who, and draws it with TopoForge. You move the shapes; the drawing is yours.

The browser app works with no server at all (“Zero Sharing”: everything stays in your browser). With a server, every feature can be switched off, down to just the app’s files on disk.

The drawing app: topology forge (formerly TopoForge)

The drawing app in www/topoforge/ is topology forge (formerly TopoForge). Bryant Frankford made it, for Corwin; he is named first, here and on everything that grows from it. Its work goes on in this branch (Corwin, 2026-11-01): what was the TopoForge project is folded in here, and topoforge/ carries its kits, specs and recipe.

The naming rule: in our own text (READMEs, NEWS, ChangeLog, documents, the app’s About box) say “topology forge (formerly TopoForge)”. Do not rename what saved drawings and pages that embed the app rely on: window.TopoForge, the TopoForge JSON format, the topoforge.* storage keys, file names, and the brand and title in the app, which a visitor opening it on its own sees. From 1.8 a page may embed it with switches (no frame, floating panels, page tabs in the overview map, a selection hook, a ready event): topoforge/spec/EMBED-v1.md.

This branch

This is the corwin branch: one of several versions being made from the same conversations, to be compared later. It starts from a request kept word for word in context/, with what was read beside it. To start your own, see context/FOR-OTHERS.md.

Try it

• No install: open www/index.html after sh bin/stage-www.sh /tmp/site, or serve /tmp/site with any web server.
• Packages: sh bin/fetch-sources.sh && dpkg-buildpackage -us -uc, then apt install the three .deb files (or only topology-www).
• Check a copy: sh bin/test.sh.

Where things are

RECIPE.org	the source of bin/, debian/ and etc/; tangle it to rebuild them
www/	the front door, the app, topology forge (formerly TopoForge) 1.11
topoforge/	topology forge’s own kits: tests, story and embedding specs, project files, recipe, patches from 1.5
www/css/egad.css	egad’s colours and type, the default palette (see below)
examples/inputloop/	the shop drawn: hosts, projects, tools, paths, people (37 files)
AGENTS.md	who commits, where work lands, what to run before a push
perl/Topology/	the command, the graph API and their modules (h2xs-shaped)
spec/	TOPOLOGY.md and the show-private rule, with shared test cases
tests/	JS tests, a11y-check.mjs (WCAG rules, with planted faults), recipe check
taxonomy/pillars.json	the four pillars; design/TAXONOMY.org reads it in prose
design/	what it should be (DESIGN), and the two questions answered (LENS)
context/	the starting request, the sources, the transcript review, ENHANCE pages
vendor/	the CPAN sources inside topology-perl, and who maintains them
debian/, etc/	packaging and settings (tangled from the recipe)
runcards/	putting it on gw26 by hand

Colours: egad

The pages use the egad design system’s colours and type by default (black on white or white on black, text at 7:1 or better). The app’s settings offer “the first palette” and a light or dark choice; both are kept in this browser only. www/css/egad.css is copied from egad’s dist/css/egad-tokens.css and says so; tests/a11y-check.mjs measures every pair the stylesheet draws.

Accessibility

node tests/a11y-check.mjs checks the two pages against the WCAG 2.1 AA rules we promise (language, one h1, heading order, landmarks, skip links, labels, names, keyboard reach, contrast in five palettes); node tests/a11y-check.mjs --plant breaks a copy thirteen ways and each must be caught. sh bin/test.sh runs both. It does not replace trying the app with a screen reader and a keyboard; please report what it misses.

Examples

examples/inputloop/ describes inputloop’s own projects as TOPOLOGY.md files, one folder each. Three are private and say private: hide; what they hold is under ## Private. After changing one, run node tests/make-examples-fixture.mjs and read the diff; Perl and JavaScript must both still agree with it.

Reading the Perl

The data modules use perl’s new class syntax; the parts an operator reads are classic Perl. perl/Topology/doc/CLASSIC-BRIDGE.pod maps one onto the other. The tests run under perl 5.44.0 (core class) and perl 5.38 (Object::Pad, through Feature::Compat::Class).

Licences

Code: GPL-3.0-or-later OR LGPL-3.0-or-later, your choice. Prose: CC-BY-SA-4.0. REUSE.toml says which covers which file. TopoForge is Bryant Frankford’s, under the same terms.