agentleFS
m-dohmenm-dohmen/openToolbox/AGENTS.md

openToolbox

AGENTS.md4 starsChanged 3 months agoApache-2.0View on GitHub

Instructions for an AI assistant asked to build a tool on the basis of openToolbox. Read this file completely before writing any code. It is short on purpose. If you are editing this file: plugin/skills/opentoolbox-tool/SKILL.md is an installable skill for Claude Code and Codex that walks a user through the same build. The split is deliberate — this file holds the knowledge (schema shape, field types, the rules that break a single-file build), the skill holds the procedure (fetch, interview,…

  • Installs packages
  • Commits and pushes
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repositoryOne other file it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

13 rules. About 0 are common, 9 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read this file completely before writing any code.

    line 5
  2. Distinctive:

    Do not guess the domain. Ask the user, in one round:

    line 26
  3. Distinctive:

    If the user gave enough detail in the prompt, skip the questions and state the assumptions you made.

    line 34
  4. Very specific:

    If compute(record) throws, the field renders as a dash and the console sees one warning per the unique combination of entity, field, record …

    line 116
  5. Very specific:

    Use it for scores (likelihood × impact), remaining time, percentages, budget variance — anything a consultant would otherwise recompute in …

    line 121
  6. Distinctive:

    Write rules for the things a reviewer would otherwise catch by eye: an item in progress with no owner, a closing date before the start …

    line 159
  7. Distinctive:

    Use them where the tool is about evidence — audit findings, certificates, invoices.

    line 214
  8. Distinctive:

    Search, facets, field filters and sort live only in the session today.

    line 523
  9. Very specific:

    Default title, subtitle, file name, colours and product name live in DEFAULT_SETTINGS, DEFAULT_COLORS and DEFAULT_BRAND at the top of …

    line 631
  10. Distinctive:

    Tell the user it exists when you hand over the file: If the tool is going to a regulated environment, or gets passed on to their client, …

    line 806
  11. Distinctive:

    Never add a runtime dependency on the network: No CDN links, no web fonts, no external images.

    line 817
  12. Very specific:

    Keep the build single-file: Do not add a second entry point.

    line 822
  13. Distinctive:

    Never delete main. Never delete a branch whose PR is still open, or one that was closed without merging until someone has confirmed its …

    line 876

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

Instructions for an AI assistant asked to build a tool on the basis of openToolbox.

Read this file completely before writing any code. It is short on purpose.

If you are editing this file: plugin/skills/opentoolbox-tool/SKILL.md is an installable skill for Claude Code and Codex that walks a user through the same build. The split is deliberate — this file holds the knowledge (schema shape, field types, the rules that break a single-file build), the skill holds the procedure (fetch, interview, build, verify, hand over), and the skill defers to this file where they overlap. Do not copy schema documentation into the skill; two descriptions of the same thing drift apart.

What openToolbox is

A template that compiles to one self-contained HTML file. No server, no install, nothing loaded from the network at runtime. The file is also the database: saving writes a new HTML file with the data embedded in it. Optional AES-256-GCM encryption, optional AI assistant that can read and — on explicit instruction — change the data. One usage counter that is on by default and switchable off (see below).

You are not building an app from scratch. You are swapping one file and rebuilding.

Before you write code: ask

Do not guess the domain. Ask the user, in one round:

  1. What is being tracked? One record — what is it called, singular and plural?
  2. Which fields? Name, type (text, enum, date, number), and for enums the allowed values.
  3. Which field is the headline in the list, and which fields belong in the table at all?
  4. Any "overdue" or "done" logic? A date that can lapse, a status that closes an item.
  5. Should the AI assistant be part of it? It ships switched off; the user can enable it.

If the user gave enough detail in the prompt, skip the questions and state the assumptions you made.

The one file you change

src/domain.js — everything domain-specific lives there and nowhere else. It exports:

ExportPurpose
SCHEMAField definitions plus presentation hints. Drives the table, the form, the sidebar filters, the CSV columns, the AI instructions and the validation of AI-proposed changes.
uid()Generates a record id. Use a readable prefix.
emptyRecord()A blank record with sensible defaults.
seed()Realistic demo records so the file is not empty on first open. Around a dozen for a single record type (the shipped examples carry 9–14); multi-entity domains seed every entity, and the counts may differ per entity.
isDone(r)Record no longer counts towards the open total.
isOverdue(r)Record is flagged in red. Return false if the concept does not apply.
formatDate(s)ISO string to display string.

Seed counts are a judgement call, not a quota: suppliers-certificates deliberately ships five suppliers because its whole point is the bare reference mechanics, and renovation-quotes carries seventeen offers because every trade holds three quotes plus rejected ones. What matters is that the file opens on something worth reading.

SCHEMA shape

export const SCHEMA = {
  idField: 'id',
  singular: 'risk',            // used in buttons: "New risk"
  plural: 'risks',             // used in the overview tile
  titleField: 'name',          // leading column, rendered with emphasis
  subField: 'category',        // second line under the title, or null
  list: ['name', 'owner', 'review', 'likelihood', 'impact'],   // table columns, in order
  facets: ['likelihood', 'category'],   // enum fields that become sidebar filters
  totalField: 'impact',                 // number summed in the overview, or null
  fields: [
    { key: 'name', label: 'Risk', type: 'text', required: true },
    { key: 'category', label: 'Category', type: 'enum', values: ['Operational', 'Legal', 'IT'] },
    { key: 'review', label: 'Review date', short: 'Review', type: 'date' },
    { key: 'impact', label: 'Impact score', short: 'Score', type: 'number' },
    { key: 'mitigation', label: 'Mitigation', type: 'text', long: true },
  ],
}

short is the table header when the full label is too wide. long: true renders a textarea in the form. Field types are enforced when the AI proposes changes — an enum value outside values is rejected and reported, so keep values accurate.

Search and field filters come free

The search box above the entity tabs reads every field of every entity — case-insensitive, live, with the hit count on each tab and the matches highlighted in the table. Attachments count by file name only, reference fields by the resolved title, computed fields and the record id like any other value. There is nothing to configure, and that is deliberate: a tool where "where does X stand" is the most common question must not fail because a new field was never added to a search list. A search: entry left over from an older schema is tolerated but no longer read — drop it when you touch the file anyway.

Below the facet groups, the sidebar gains one field filter per text, enum, number and date field that is not already a facet: contains, multi-select, from/to. Fields listed in facets stay quick filters with their counts and do not appear twice. Active filters show as removable chips above the table; an entity without filterable field types gets neither filter area nor chips. All of it lives in the session only — none of it enters the payload, and a reload starts clean (deliberately without localStorage, see the rules below).

Calculated fields

Anything derived from other fields belongs in a computed field rather than in a number field the user has to keep up to date by hand:

{ key: 'score', label: 'Risk score', type: 'computed', compute: (r) => r.likelihood * r.impact }

compute(record) runs once per record per render pass and the result is memoised on the record object for the lifetime of the page. The value is never written into the record — a stored derivation goes stale the moment one of its inputs changes and nobody notices. It behaves like any other field in the table, in sorting, in search, in totalField and in the CSV export; it shows read-only in the form; and both the user and the AI are prevented from setting it (the AI is told it is read-only and a write is rejected by name). Same posture in the metric catalog: a computed field whose compute returns a number stands in for a real number field in sum(field) and avg(field).

If compute(record) throws, the field renders as a dash and the console sees one warning per the unique combination of entity, field, record id and error message — the table does not stop, but neither does the error drown the developer in identical stack traces. The next render pass will try again.

Use it for scores (likelihood × impact), remaining time, percentages, budget variance — anything a consultant would otherwise recompute in a spreadsheet and paste back in wrong.

Validation rules

required: true on a field is enforced. Beyond that, conditions between fields belong in rules on the schema — a per-field type check cannot see them:

rules: [
  {
    when: (r) => r.status === 'done',        // optional; without it the rule always applies
    require: ['cost'],                       // shorthand: these fields must be filled
    check: (r) => Number(r.cost) > 0,        // optional predicate; true means fine
    fields: ['cost'],                        // which fields to flag; defaults to `require`
    message: 'A closed item needs its actual cost.',
  },
]

The point is the single place it runs. The form, the CSV import, the wizard's CSV step and AI-proposed changes all pass through the same check — one rule in the schema hardens all of them at once instead of being retrofitted in four places. In the form the objection appears under the offending field and the save is refused; in the import the row is skipped and named; the AI is told the message up front and gets it back as the reason if it proposes something that violates it. The JSON import runs every incoming record through the same type and rule check plus an id check (missing or duplicate ids are rejected); it is atomic — one violation rejects the whole file, because Trail-Diff and the audit log key records by id and cannot survive half-applied imports.

Two details worth knowing when you write rules:

  • A number 0 counts as filled. require treats empty string, null and undefined as missing, nothing else — a cost of zero is usually a real answer.
  • message is your text, in your language, like the field labels. Only the built-in "X is required." comes from the interface translation.

Write rules for the things a reviewer would otherwise catch by eye: an item in progress with no owner, a closing date before the start date, a mandatory justification on a rejection. Do not recreate type checks — enum, date and number are already enforced.

The examples are the fastest way in

examples/ holds eight complete domains; six of them are built and published under docs/demos/. risk-register.domain.js and suppliers-certificates.domain.js ship as examples without a demo — the first is the plainest starting point, the second exists to show the reference mechanics alone and doubles as the build fixture for the multi-entity test. Before writing one from scratch, open the closest and copy its shape:

FileShape worth stealing
risk-register.domain.jsThe plainest single-entity domain.
portfolio.domain.jsTwo record types, a reference, money, a dashboard with inline-SVG charts.
suppliers-certificates.domain.jsTwo record types, minimal — the reference mechanics alone.
ppwr-packaging.domain.jsComputed fields that aggregate a child entity; rules that force a source for every estimate.
gdpr-processing.domain.jsAlmost no numbers — enums and free text; built for mode: 'intake'.
equipment-testing.domain.jsEverything derived from dates: due date from interval, days left, the red flag.
renovation-quotes.domain.jsMoney across two entities; the awarded sum is read from the accepted quote, never typed.
school-trip.domain.jsStates rather than numbers, and a domain that argues for encryption.

Copy one over src/domain.js and build to see the whole app change.

Each demo also carries a build prompt — docs/demos/<slug>/generating_prompt_<lang>.md, seven languages — which states the same domain as a functional specification. If a user hands you one of those, it is complete: follow it and you get the demo back. They are generated from the domains by npm run prompts, so never edit one by hand; change the example and regenerate.

Attachments

type: 'attachment' stores an uploaded file in the record itself, base64 in the payload, and it travels with the file like everything else:

{ key: 'evidence', label: 'Evidence', short: 'File', type: 'attachment' }

The budget is part of the feature, not an extra. Attachments break the one promise this shape rests on — a file you can send by email. Without a hard limit the third scan turns a 200 KB tool into a 30 MB attachment no gateway will pass, and nobody would notice. So:

  • A meter sits in the dark bar showing used-of-limit, and turns amber past 85 %.
  • The limit is attachmentBudgetMb in DEFAULT_SETTINGS, 5 MB by default, editable in Settings → Data. An upload that would exceed it is refused when the record is applied, with the numbers in the message — not tolerated and discovered later.
  • One file is capped at 4 MB regardless.

Three things attachments deliberately do not do: they never reach the AI (the model sees only the file name — one embedded PDF as base64 would exceed the whole context window), the CSV export carries the file name and not the content, and the stored MIME type is never used to render anything. Downloads always go through a blob with a download attribute.

Use them where the tool is about evidence — audit findings, certificates, invoices. Do not add an attachment field "just in case": every one of them is an invitation to make the file unsendable.

Multiple entities and relationships

Most tools need only one record type — stick with the single SCHEMA export above. Reach for this only once there are genuinely two or more kinds of records that reference each other, e.g. "suppliers" and "certificates", where a certificate always belongs to a supplier.

Export ENTITIES instead of SCHEMA, one entry per record type, each shaped like the single-entity exports above but nested under a key:

export const ENTITIES = {
  suppliers: {
    schema: { idField: 'id', singular: 'supplier', plural: 'suppliers', titleField: 'name', /* … */ },
    uid: () => 'S-' + /* … */,
    emptyRecord: () => ({ /* … */ }),
    seed: () => [ /* … */ ],
    isDone: () => false,
    isOverdue: () => false,
  },
  certificates: {
    schema: {
      idField: 'id', singular: 'certificate', plural: 'certificates', titleField: 'title',
      fields: [
        { key: 'title', label: 'Title', type: 'text', required: true },
        { key: 'supplierId', label: 'Supplier', type: 'reference', entity: 'suppliers', required: true },
        // …
      ],
    },
    uid: () => 'C-' + /* … */,
    emptyRecord: () => ({ /* … */ }),
    seed: () => [ /* … */ ],
    isDone: () => false,
    isOverdue: (r) => r.expiry && r.expiry < today,
  },
}
export const formatDate = (s) => /* … */   // one shared export, same as the single-entity shape

A type: 'reference' field points at another entity via entity: '<key>'. The app renders it as a dropdown of that entity's records (showing the title field, storing the id) in the edit form, and as a clickable chip resolving to the referenced record's title in the table — clicking it switches to that entity and opens the record. Deleting a record that's still referenced by another entity is blocked, and the message names what references it. The AI assistant's instructions and proposal validation are reference-aware too: it can name the target record by id or by its title text.

examples/suppliers-certificates.domain.js is a complete working example — copy it over src/domain.js and rebuild to see a two-entity tool with a working relationship between them.

Everything else — CSV/JSON export, encryption, branding, the interface language toggle — already understands this shape without any further change.

The start page

A tool that lands straight on a table assumes the recipient already knows what it is. Usually they do not — they want a sentence on what this is for, who maintains it and where to ask.

DEFAULT_HOME at the top of src/app.jsx holds that text, and the app opens on it whenever it is not empty. Write it for the tool you build. It is the first thing your user's recipients see, and the shipped default talks about openToolbox rather than about their tool.

The text is a small Markdown subset — #/##/###, - and 1. lists, > quotes, ---, **bold**, *italic*, `code` and [text](url). Everything else stays plain text: it is parsed into a tree and rendered as nodes, never inserted as HTML, so nothing in that field can become markup in a file that gets passed around.

Two things to know:

  • Editing happens on the page itself, and the settings lock covers it. Protect the settings and the Edit this page button becomes a note saying so — otherwise the protection would be half a measure, since this is where it says what the tool is.
  • The text lives with the settings, so it sits outside the encrypted envelope and stays readable before anyone unlocks the file. That is right for "what is this" and wrong for anything confidential. Say so if the tool is encrypted.

Set it to '' when a start page would only be a click in the way — a tool someone opens twenty times a day does not need one.

Optional: a guided entry wizard

The list plus the edit form assume the recipient knows the tool. Someone who gets the file in order to report one thing should not have to sort out a table, a sidebar and seventeen fields first. A WIZARD export gives them a sequence of short steps instead — without it the view does not exist:

export const WIZARD = {
  title: 'Report a finding',
  intro: 'Four short steps. Nothing is written until the last one.',
  steps: [
    { id: 'what', label: 'What', fields: ['title', 'area', 'note'] },
    { id: 'who', label: 'Who and when', fields: ['owner', 'due', 'status'],
      when: (drafts) => drafts.records.severity !== 'low' },
    { id: 'bulk', label: 'Several at once', type: 'csv' },
    { id: 'check', label: 'Check', type: 'review' },
  ],
  done: { message: 'Thank you — that is recorded.', allowAnother: true },
}

Four step types, which is all it takes generically:

  • fields — a subset of the schema fields, rendered by the same machinery as the edit form, with the same validation rules. A step only reports objections about the fields it actually shows.
  • csv — the existing import as a step, for bulk entry. It feeds the same run: rows are held and created together with the draft at the end, so abandoning the wizard leaves nothing behind.
  • review — a summary generated from the schema. Nothing to configure.
  • the closing screen, built from done. allowAnother: false ends the run for good.

when(drafts) hides a step that does not apply; drafts is keyed by entity, so with a single record type it is drafts.records.

With ENTITIES, a step carries entity: '<key>' and one run can create a supplier and then its certificates. The drafts get their ids at the start of the run, which is what lets a reference field in step two point at the record from step one — the dropdown there offers the draft alongside the saved records.

Intake mode

mode: 'intake' in DEFAULT_SETTINGS opens the file straight into the wizard and hides the list, the entity tabs and the "New …" button. That turns the same file into a form you send out: the recipient fills it in, saves, mails it back. Without a WIZARD export the switch does nothing.

Set it when the recipient's job is to report, not to browse. Leave it on 'workbench' — the default — when they also need to see and edit what is already there.

Optional: a dashboard

Consultants analyse and then present. If the tool is for anything that gets shown to a steering committee, add a DASHBOARD export — without it the view simply does not exist:

export const DASHBOARD = {
  tiles: [
    { type: 'stat',  measure: 'count', label: 'Risks', caption: 'in this file' },
    { type: 'stat',  measure: 'impact', filter: (r) => !isDone(r), label: 'Open impact' },
    { type: 'donut', groupBy: 'likelihood' },
    { type: 'bar',   groupBy: 'category', measure: 'impact', label: 'Impact by category' },
  ],
  // OPEN-103: zusaetzlicher Block fuer Inline-SVG-Diagramme (Balken/Donut/Linie)
  // unter dem neuen einheitlichen 'type: chart'. 'tiles' daneben ist weiterhin
  // erlaubt - beide Renderschienen koexistieren.
  charts: [
    { type: 'chart', kind: 'bar',   groupBy: 'category', measure: 'impact', label: 'Impact by category' },
    { type: 'chart', kind: 'donut', groupBy: 'likelihood' },
    { type: 'chart', kind: 'line',  dateField: 'review', aggregate: 'count', label: 'Reviews per month' },
  ],
}
  • stat — one number. measure: 'count' or a field key whose values are summed. filter(record) narrows the set first. label and caption are free text.
  • bar / donut — die alten Kacheltypen, gezeichnet als Inline-SVG (Balken als <rect> mit Achse, Donut als Kreis mit stroke-dasharray). Funktionieren weiter wie bisher; wer neue Diagramme baut, schreibt heute type: 'chart'.
  • chart — der neue einheitliche Baustein (OPEN-103). kind waehlt zwischen bar, donut und line. line aggregiert ueber dateField je Monat (aggregate: 'count' oder 'sum' mit field). Andere Aggregate sind bewusst nicht im Katalog - wer mehr braucht, soll die Datei verstehen und bewusst erweitern, nicht ueber eine string-evaluiert Formel aus Versehen Code einschleusen.
  • entity — nur noetig mit ENTITIES; faellt auf die gerade offene Entitaet zurueck.

Drawn without a charting library: every diagram is pure Inline-SVG (Balken, Linien, Kreise, Pfade) - eine Chart-Bibliothek wuerde die Einzeldatei um ein Vielfaches dessen aufblaehen, was hier tatsaechlich gebraucht wird. Category colours werden aus der Akzentfarbe des Werkzeugs abgeleitet, ein Rebrand faerbt das gesamte Dashboard automatisch. Tiles und Charts zeigen den vollstaendigen Bestand ihrer Entitaet, nicht die gefilterte Tabellenansicht.

Eine verworfene Deklaration (unbekanntes Feld, fehlender aggregate, sum ohne field) erscheint als eigene Kachel mit dem Grund im Klartext - genau wie bei den Metriken. Eine stille Verwerfung waere genau die Stelle, an der ein Reihenfolge-Bug erst beim Kunden auffaelt.

Both the list and the dashboard have a print stylesheet - der Browser macht das PDF, alles Bedienbare faellt weg. Diagramme werden schwarzweiss gestrichelt statt in Akzentfarbe gedruckt, damit die Lesbarkeit auch auf einem Drucker ohne Farbprofil stimmt.

Due dates on the dashboard

Set dueDate on a schema to a field key — a plain date field or a computed one, the same way totalField points at a number field — and a "Fälligkeiten"/"Due dates" widget appears at the top of the dashboard automatically:

export const SCHEMA = {
  // …
  dueDate: 'review',   // field key holding the date to track, or leave unset
}

This is deliberately not a DASHBOARD export. Fälligkeitssteuerung is the most common reason a consultant opens one of these tools at all — it should not depend on someone also having built stat tiles. So the widget shows up on its own even without a DASHBOARD export, as soon as any entity declares dueDate. Domains that never mention it see exactly their old dashboard, tiles or none.

Three groups, hidden when empty: overdue (before today), this week (Monday through Sunday of the current local calendar week) and the next 30 days after that Sunday. Group boundaries are fixed in this version, not configurable — a setting here would be one more thing to explain to a recipient who just wants to know what is late. A record where isDone(record) is true is excluded from all three groups; a finished item is not "due" in any group, and counting it as overdue would flag closed work as outstanding. Comparisons run on local calendar dates parsed from the field's ISO string, not on the UTC instant new Date('2026-08-20') would give you — that constructor lands on the previous day everywhere west of Greenwich, which is exactly the kind of off-by-one nobody notices until a steering committee meeting starts with the wrong item flagged red.

With ENTITIES, the widget aggregates across every entity that declares dueDate — a portfolio tool can flag an overdue milestone and an overdue action item in the same list. Clicking an entry switches to that record's entity and opens it, using the same navigation as a reference chip.

The widget's clock is a parameter, not a call to new Date() buried inside it — an "overdue" bucket that can only be exercised against whatever day the test happens to run on is not really tested. You will not normally touch this; it matters if you extend the widget yourself.

Metric tiles from the schema

Overview numbers — how many records, what do they weigh in total, what is the average score — should not have to be counted by hand or recomputed in a spreadsheet. A schema can declare them directly: metrics on the schema, one tile per entry, rendered at the top of the dashboard above every other widget. Like dueDate, a metrics declaration unlocks the dashboard view on its own — no DASHBOARD export required:

export const SCHEMA = {
  // …
  metrics: [
    { op: 'count', filter: (r) => !isDone(r), label: 'Open risks' },
    { op: 'sum',   field: 'impact', label: 'Total impact', caption: 'across all risks' },
    { op: 'avg',   field: 'impact' },   // default label: "Ø Impact score"
  ],
}

The catalog is closed: exactly three operations — count (optionally narrowed by a filter(record), same semantics as the stat tiles), sum(field) and avg(field) over numeric fields. There is deliberately no fourth form — no expression string, nothing that gets evaluated — because the output file is passed around by hand, and a declaration that could carry code would make every recipient of the file an executor of it. New shapes join the catalog in src/lib/metrics.js or they don't exist.

Details worth knowing:

  • Labels fall back sensibly when omitted: count carries the schema's plural, sum and avg prefix the field's label (Σ, Ø). caption is free text.
  • Values are computed locally at render time over the entity's full record set — never written into the record or the embedded data block, same posture as computed fields. A domain without any metrics declaration renders exactly its previous dashboard.
  • Formatting follows the surface language: integers stay integers, avg stands at two decimal places — otherwise 7 would read as 7 one day and 7.333 the next, depending on the stock — and the average of an empty set is a dash rather than an invented zero.
  • Clicking a tile switches to that entity's list (keyboard included). In this version unfiltered; pre-filtering is reserved for after search and filtering exist, so a tile never implies a narrower count than the one it actually performs.
  • Invalid declarations are rejected by name, not silently skipped. An unknown operation, a missing field or a non-numeric target appears as its own rejection tile between the valid ones, with the reason in the interface language. A metric that quietly switches itself off is noticed only when somebody misses the number.

Inline-SVG charts in the dashboard (OPEN-103)

A DASHBOARD export can carry a charts array alongside tiles - the old kinds stay alive so existing examples keep working, the new form is for fresh diagrams. Three kinds, all rendered as Inline-SVG without a charting library, without external requests, without <script>:

export const DASHBOARD = {
  /* tiles: [...],  — bleibt unveraendert, falls vorhanden */
  charts: [
    { type: 'chart', kind: 'bar',   groupBy: 'area',     measure: 'effort' },
    { type: 'chart', kind: 'donut', groupBy: 'status' },
    { type: 'chart', kind: 'line',  dateField: 'due', aggregate: 'count' },
    { type: 'chart', kind: 'line',  dateField: 'due', aggregate: 'sum',  field: 'effort' },
  ],
}
  • bar — one bar per value of groupBy (an enum or reference field). Bars share a single SVG with proper axis ticks; the largest bar reaches the top tick rather than clinging to the edge.
  • donut — same data as a ring with a legend. Sum of segments equals the total printed in the centre, both checked at render time.
  • line — monthly time series over dateField. aggregate: 'count' counts records per month; 'sum' sums a numeric field per month. Months without data are skipped, the line jumps over them rather than faking values. Computed fields are accepted as field (same posture as metrics).
  • entity — only needed with ENTITIES; defaults to the entity being viewed.
  • i18n axes: the chart label takes its label from the matching schema field ("Review date · count", "Effort · sum of Effort"), the chart title is set automatically from the same source.

The whole renderer lives in src/lib/charts.js as pure functions (prepareBarRows, prepareDonutRows, prepareLinePoints, niceScale, linePath, validateChart) so the math can be tested without a browser. The dashboard components consume them; they do not rebuild the math themselves. Invalid declarations - unknown groupBy, missing dateField, sum without a numeric field - are listed under a rejection tile, not silently dropped.

Both the list and the dashboard have a print stylesheet. Charts switch to black-and-white stroke patterns so the printout stays readable on a printer without a colour profile.

Optional: saved views

Search, facets, field filters and sort live only in the session today. A tool that gets opened the same way every Monday morning ("my open items", "overdue", "this quarter") makes the recipient rebuild that combination by hand each time. A views array on the schema declares named combinations the dropdown at the list head offers — they ship with the tool and the recipient never has to know they exist as a feature:

export const SCHEMA = {
  // …
  views: [
    {
      name: 'Open of mine',
      query: '',
      filters: { owner: { v: '', op: 'contains' } },
      sort: { key: 'due', dir: 1 },
    },
    {
      name: 'Overdue',
      query: '',
      filters: {},
      sort: { key: 'due', dir: 1 },
    },
  ],
}

Each entry holds the same shape the running list uses: query is the global search input, filters is the field-filter bag from the sidebar ({ key: { v, op } }), sort is { key, dir } (dir is 1 ascending, -1 descending) and entity is optional — it points at the entity the view belongs to when there is more than one. Anything the dropdown sets lands in the session (query, facets, filtersByEntity, sort), not in the record set; the view itself is just a named template.

Two reasons the recipient's own views live elsewhere: schema files are read-only once shipped, and the same view in two files has to merge by name. Stored views sit in the data block under settings.views; the schema's views array is the catalogue, the file's views is what the recipient has actually used. Both are merged in lib/views.js: same name = stored view wins.

A single settings.startView (the name of a view) marks the one that auto-applies when the file opens — the same way mode: 'intake' opens straight into the wizard. Empty string means no auto-applied view. The Settings page has a small editor next to the application block: list of current views with rename, delete and "open with this view"; one input at the bottom that captures the running search/filter/sort under a chosen name (the capture button only lights up when there is actually something to capture).

The merge is in lib/merge.js and is intentionally one-line from the caller's side: applyMerge takes an optional { views: { mine, theirs } }, runs mergeViews, and returns the result as nextViews alongside the data. Two files with disjoint view lists merge without conflict; two files with the same view name keep the other side's last edit. A renamed or removed view in one file is just a new entry in the merged set — there is no delete signal across files because the recipient that never used the view never saved it, and dropping a shared view on a single merge would surprise the other side.

Optional: a Kanban board per entity

The list view is the default, but a tool whose records move between statuses - audit findings, work items, tickets - is often faster to read as a board. A view.board declaration on the schema adds the "Board" tab next to "List" and "Dashboard"; without it the view does not exist, the same posture as DASHBOARD and WIZARD:

export const SCHEMA = {
  // …
  view: {
    board: {
      columnField: 'status',                 // enum field that becomes the columns
      cardFields: ['owner', 'due', 'effort'], // optional: up to three fields on each card,
                                               //   in addition to the title
      limit: 50,                              // optional: per-column card limit, default 50
    },
  },
}

columnField must point at an existing enum field - the columns take their values and their order straight from the schema's values, so open always sits at the left end regardless of where the records sit in the data block. Records whose value is empty or no longer in values land in a small "Unassigned" reservoir at the right; a card that belongs to no column would otherwise be unfindable, and pretending the first column catches them would silently mis-categorise.

cardFields defaults to the first three non-computed, non-attachment, non-title, non-column fields in the schema. Computed fields render via the same fieldValue path as the table; date fields render through entity.formatDate; enum values get the same pill styling as the table. A record opened from a card still uses the regular record drawer - the board does not invent a new edit surface, it just offers another way to set one field.

A drag from one column to another sets the enum field through the normal change path: the same mutate function the form uses, which means the change lands in the Undo/Redo stack and in the change log, exactly as a form edit would. Read-only copies render the board but disable dragging - the same settings.readOnly flag the rest of the UI watches.

Keyboard works end-to-end: a focused card responds to Left/Right to step between columns, Enter to commit the move, Escape to abort it. The pending move lives in the session, not the data block

  • an Escape is a no-op for Undo because nothing changed yet. 200+ cards in a single column are not silently clipped: a banner appears above the column naming the limit and the actual count, and the column shows only the first limit cards. Anyone who wants the full set switches to the table.

Touch uses the HTML5 drag-and-drop API, which works natively on iPadOS 15.4+; the same keyboard arrows cover an attached keyboard on iPad. There is no second entry point and no new dependency - the board ships inside the same single-file build.

Optional second file

src/app.jsx — only if the user needs something the schema cannot express: an extra sidebar section, a computed column, a different empty state. Everything else is already generic. Resist the urge to touch it.

Default title, subtitle, file name, colours and product name live in DEFAULT_SETTINGS, DEFAULT_COLORS and DEFAULT_BRAND at the top of src/app.jsx. Set them to match the tool you are building — the user can change all of them later in the settings page.

The dark bar at the top

Two more settings live there, both aimed at a tool that leaves your hands:

  • tagline — the text after the file name. Empty means the translated standard line, which follows the interface language; set it and your text wins in every language. Good place for the client, the department or the classification (Muster GmbH · internal).
  • links — up to five icons on the right of the bar, each { icon, url, label }, opening in a new tab. Ships with one entry pointing at the openToolbox repository. Replace it when you deliver, the same way you replace copyright: the recipient's repository, their Confluence space, their ticket board — a link back to the template is rarely what they need there.

    links: [
      { icon: '<svg viewBox="0 0 16 16">…</svg>', url: 'https://intranet.example/qm', label: 'QM handbook' },
    ]

    icon is inline SVG and runs through the same sanitiser as the logo — an empty string draws a neutral chain link. url accepts http, https and mailto; a missing scheme is completed to https, and anything else (javascript:, data:) is dropped without display. label becomes the tooltip and the accessible name, so write one.

Merging a copy that came back

The one thing this shape does not solve on its own: send the file to five departments, get five files back. Since v0.4.0 the tool reads a second copy of itself and compares record by record — Merge a file in the sidebar, or Settings → Data.

Nothing about it needs configuring; it works off the schema and the identifiers. What you should tell the user:

  • It is for two copies of the same tool, not two arbitrary files. Same schema, same ids. A record type the reading file does not know is named and skipped.
  • Three groups, each with checkboxes: records only in the other file, records with different values (shown field by field, before and after), and records missing there.
  • Deletions are not preselected. The other copy being older looks exactly like a record having been deleted, and only one of those two readings destroys data. Everything else is preselected, because taking the changes is why anyone opens this dialog.
  • An encrypted counterpart asks for its passphrase. Two files, two secrets.

Nothing is written to disk by merging — it changes the working set, and the file still has to be saved afterwards.

Handing out a read-only copy

Sharing a working file hands the recipient the keys to it. Export a read-only copy in the sidebar makes a second HTML file with every write surface stripped: no Save, no Undo, no Redo, no Wizard, no AI proposals, no Import, no Merge, no Settings page, no row-edit drawer. The export action lives in the same sidebar.exchange group as the CSV/JSON export — it is a hand-out, not an edit path, and the rest of the sidebar stays where it always was.

What changes between source and copy:

  • The copy carries settings.readOnly: true. The whole UI watches the flag and renders the read-only variant: settings icon and New button hidden, undo/redo gone, bulk select disabled, row click no longer opens the edit drawer. Reference chips still resolve, but only by switching the entity — opening the referenced record would be a write surface.
  • A header banner sits above the file bar with the export label, the version carried from settings.version and the export timestamp. The banner is the signal: a recipient who sees it knows the file cannot be saved, even before they try.
  • The filename is <fileStem>-report-<YYYY-MM-DD>.html. The export always uses the same date helper as a normal write — keep the two consistent so a search for report- lands only on copies.
  • The source's change log gets an entry "Berichtskopie exportiert" (or "Read-only report copy exported" in English). It is added to the in-memory log at click time and lands on disk the next time the source is saved; without that entry nobody can later tell which report came from which revision.

The same single-file build path produces both source and copy. The export is a plain buildDocument(reportPayload) over a payload where auditLog, ai.enabled and mode are forced to a safe default — no second bundle, no separate Vite entry.

Getting the user's real data in

You do not have to write an importer, and you should not paste the user's data into seed(). The built file imports CSV itself: the user picks a file, assigns columns to fields in a dialog, and every cell runs through the same type check as an AI-proposed change. Separator, quoting and BOM are detected. Identifiers are always assigned by the app, never read from the file.

Two consequences for the schema you write:

  • Field labels drive the automatic column mapping. A column heading that matches a field's label or key — ignoring case and punctuation — is preselected. If the user showed you a sample of their spreadsheet, name the fields the way their columns are named and the mapping is right on the first try. Anything unmatched the user assigns by hand, so a mismatch costs a click, not a failed import.
  • Keep values of an enum aligned with what their data actually contains. Enum matching is tolerant about case and spacing, but erledigt will not match done. Either use their wording as the enum values, or expect those cells to be reported as objections.

seed() stays what it is: demo records so the file is not empty on first open. Tell the user they can replace them via Import CSV → replace all.

Build and deliver

npm install
npm run build          # produces dist/index.html — one file, self-contained
npm test               # optional: headless smoke test, needs a chromium download

Deliver dist/index.html. Rename it to something meaningful. Tell the user:

  • double-click to open, no server needed
  • Ctrl/Cmd+S or the Save button writes a new HTML file containing the data
  • nothing is auto-saved; the amber dot in the top bar means unsaved changes
  • many mail gateways strip .html attachments — send it zipped
  • their own data goes in via Import CSV; the shipped records are demo data
  • the version badge and the change log are theirs to fill — the dialog on save asks for both
  • the file counts its own opens (Settings → Security), preset to the template author's endpoint — they can point it at their own or switch it off; see below

Before you hand over: two switches

Both default to on because the template's job is to teach. A finished tool for a client is a different situation, and this is a judgement call you should make yourself rather than leave to the recipient:

  • examplePrompts — hint boxes with ready-made prompts at every place worth changing. Perfect while the tool is still taking shape, noise for someone who only enters data. Set examplePrompts: false in DEFAULT_SETTINGS when you deliver a finished tool, or tell the user where the toggle is (Settings → Appearance).
  • auditLog — one entry per save, with a short dialog asking what changed. Keep it on wherever changes have to be justifiable (audits, regulated processes, anything with a steering committee). Switch it off for a scratch tool where the dialog is just friction.

    Since v0.5.0 each entry also carries the field changes since the last save, worked out automatically: which record, which field, before and after, plus records created and deleted. The entry answers "what happened to A-1041 between 1.2 and 1.4", which is the question that actually gets asked. Deriving it rather than asking for it is the point — a log that depends on the writer's discipline is incomplete exactly when it is needed. The record form shows the same trail filtered to that one record. Capped at 200 changes per entry, with the remainder counted rather than silently dropped.

version is empty by default. Set it in DEFAULT_SETTINGS if the tool has a meaningful starting version; otherwise leave it and let the user set one at the first save.

Set copyright to whoever owns the tool. It defaults to '© openToolbox' with a link to the template, which is right for a fresh checkout and wrong for anything you deliver — the notice at the bottom of the settings page belongs to your user or their client, not to the template it was built from. Set copyright and copyrightUrl in DEFAULT_SETTINGS, or tell the user where to change them (Settings → Application). The based on openToolbox line underneath stays either way and is not editable.

Locking the settings against accidental change

A tool that goes to someone who only enters data has a settings page they have no reason to open — and every reason to leave alone. One stray click on a colour, an endpoint or the file name and the next save carries it forward. Settings → Security → Protect settings asks for a word and disables every control on that page; the fields stay visible with their values readable, and the same word enables them again for the current session. Reopening the file locks them again.

Suggest it whenever the recipient is not the person who built the tool. Two things to say plainly when you do:

  • This guards against slips, not against people. Whoever holds the file holds the code; the lock entry can be removed from the payload. It is a lid on a switch, not a lock on a door. If something in the file genuinely must not be read, that is what the encryption is for.
  • The word is not a password. It is stored as a salted SHA-256 digest so it does not sit in the file in plain text, but the input field shows it openly on purpose — nobody should reuse a real password here, and 123 is a perfectly good choice.

You can preset it: lock in DEFAULT_SETTINGS takes null (open, the default) or a { salt, hash } pair. Producing that pair by hand is rarely worth it — protect the file once through the settings page and save.

The usage counter — mention it, don't hide it

A built file sends one GET on open, to the endpoint in settings.analyticsUrl, carrying only the kind of tool (SCHEMA.singular). No records, no field contents, no file name.

Tell the user it exists when you hand over the file. If the tool is going to a regulated environment, or gets passed on to their client, say so plainly and point at Settings → Security, where the endpoint is spelled out and the switch sits. Two honest sentences at handover cost nothing; a counter someone discovers later in a network log costs trust.

Set analytics: false in DEFAULT_SETTINGS (src/app.jsx) when building for an environment where outbound traffic is a problem at all — an air-gapped machine, a client that reviews every connection. That is a judgement call you may make yourself; do not quietly leave it on and hope.

Rules that are not negotiable

  • Never add a runtime dependency on the network. No CDN links, no web fonts, no external images. Everything needed to render must be inlined; the file must work with the network cable pulled. The usage counter is the single, documented, switchable exception — do not add a second one.
  • Never use localStorage or IndexedDB for the data. Both are unreliable under file://. The embedded payload is the storage mechanism.
  • Keep the build single-file. Do not add a second entry point; vite-plugin-singlefile supports exactly one.
  • Do not set removeViteModuleLoader: true in the Vite config. It silently empties the inlined script and produces a 9 KB file that renders nothing.
  • Do not weaken the SVG sanitiser or the action validation. Both exist because the output file gets passed around.

The first rule above is machine-checked, not aspirational: CI runs node scripts/check-self-contained.mjs dist/index.html docs/demo docs/demos on every build, and it fails on anything a renderer would fetch by itself — external <script src=, <link href=, <img>/<image>, <iframe> and media tags, <use href>, srcset, CSS @import, and CSS url() pointing at the network. Plain <a href="https://…"> links are deliberate content and stay allowed. The GitHub Pages deploy (pages.yml) runs only after its own build job has passed the same check, so a broken main is never published. One residual gap is known and accepted for now: all repository activity shares one GitHub identity, so "CI green before merge" and "nobody merges their own PR" rest on review discipline rather than GitHub enforcement until required status checks and separate merge permissions exist (tracked in the project wiki, Testing).

A second gate keeps CHANGELOG.md honest: every PR that touches it runs node scripts/lint-changelog.mjs (workflow .github/workflows/lint-changelog.yml), which enforces [Unreleased] as the first section, strictly descending semver order below it, a link definition for every version whose target tag exists on origin, and no external host outside {github.com, keepachangelog.com, semver.org}. The four checks are the ones an out-of-order file silently slips past review (OPEN-120/OPEN-121); the gate is PR-only because on main the GitHub-Release job is what catches the equivalent problem, and violations cannot enter except via a PR.

A third gate keeps the test-suite documentation honest: every PR runs node scripts/check-suite-drift.js (workflow .github/workflows/build.yml) as a mandatory step before npm test, holding scripts.test in package.json in sync with the five places the suites are enumerated — README.md, README.de.md, CONTRIBUTING.md, .multica/agents/_produkt.md, and .multica/agents/entwickler.md (OPEN-124).

Delete the branch as part of the merge

The repository does not delete head branches automatically (delete_branch_on_merge is off, and turning it on needs owner rights). So the merge is not finished when the PR closes -- it is finished when the branch is gone.

Whoever merges a PR deletes its head branch in the same step:

gh pr merge <nr> --squash   # or --merge / --rebase, as agreed
git push origin --delete <branch>   # same step, not "later"

This matters more than it looks. Merges here are squash merges, so the original branch keeps commits that never literally entered main -- git branch --no-merged lists it as unmerged forever, even though its content shipped. Left alone, the branch list stops telling you anything: on 2026-08-29 it held 20 branches, 17 of them long since delivered, and the two genuinely open questions were invisible in the noise.

Never delete main. Never delete a branch whose PR is still open, or one that was closed without merging until someone has confirmed its content reached main some other way -- name the commit or the file that proves it, in the issue.

When the user wants more than a list

openToolbox is a records-with-fields tool. If the request is a calculator, a canvas, a diagram editor or a wizard, say so plainly and offer either a stripped-down variant (keep the file persistence, encryption and AI plumbing, replace the list view) or a different starting point. Do not force an unrelated shape into the table.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.