A description of the TBX file structure—optimised for AI

mwra · July 4, 2026, 9:04pm

This is the file mentioned in the TB meet-up, that describes for an AI the Xml structure of a TBX, i.e. the XML tags and their purpose:

The_XML_TBX_format.html.zip (26.8 KB)

(A single HTML file, no styling/JavaScript, but .html files can’t be uploaded in that form)

Notre that as well-formatted HTML5, the document is perfectly human readable is a but spartan. there’s not styling as that is waste of AI token, there extra info doesn’t help the AI understand the subject matter any better.

The file was developed alongside v11.7.0 and should be accurate for v11.8.0 when released, and later unless/until subsequent public releases change the TBX files structure.

I suspect it may be useful to those use AI/MCP with Tinderbox.

The seeding source material for the project was this section of aTbRef but that required extensive expansion and re-structuring to make the eventual document above (which, yes, is exported from a TBX file). A project aim was to use minmal data (use of context tokens) whilst still properly defining the document structure.

macgarvin · July 17, 2026, 11:40pm

Always interested in what you are up to - Care to elaborate a little bit more on the utility of this (or how many minutes into the chat when you introduced it).

Estomm · July 18, 2026, 8:39am

I share this simply as practical feedback from my own experience. It’s not intended as a critique or the start of a debate; I just thought the observations might be useful.

Me: How useful did you find Mark Anderson’s XML reference as grounding for AI?

Claude (verbatim):

On the reference doc itself — genuinely useful, and worth explaining exactly where:

Where it earned its keep: When AppleScript’s make new user attribute command silently failed (created nothing, no error), I fell back to hand-editing the saved .tbx XML directly. That only worked because the doc gave me precise, checkable facts: the attrib element’s exact attributes (Name, parent, editable, visibleInEditor, type, default, suggested), the numeric type codes (5=date, 2=number, 8=set), and how a prototype is marked ($IsPrototype = “true” as a child attribute element, not an XML attribute). I wrote that XML once, reopened it in Tinderbox, and it loaded clean — correct types, correct prototype recognition, no repair dialog. That’s a strong sign the document is accurate, not just plausible-sounding.

Where it has a gap: It documents the file format only — nothing about the live AppleScript/scripting dictionary. That’s a separate thing (Tinderbox.sdef, buried in the app bundle) that I had to go find and read myself once the scripting approach started failing. A companion doc covering the scripting API the same way this one covers the XML would’ve saved me the failed make new user attribute attempts entirely.

So: for the specific job it says it’s for (“give an AI enough grounding to parse and write TBX XML correctly”), it worked as advertised — I trusted its numbers and they were right. It just doesn’t extend to “how do I drive a running Tinderbox instance,” which is a different problem I had to solve separately.

Estomm · July 18, 2026, 9:17am

As we wait for Anderson to reply, this is how I used it with Claude Code. As for when, I introduced it at the start of the conversation. Claude initially read only the first section and summarized it, noting that the full document was about 65k tokens.

Me: I’d recommend to you to read the entire document and keep every part of it that is required so that in future when we’re working we don’t need to do this part again. And we’ll be working quite a bit with Tinderbox.

Claude (verbatim):

I’ve now read the full document (all 3964 lines). Writing this up as durable, distilled reference memory — not a copy of the doc, but comprehensive coverage of the schema.

Done — I read the full 3964-line document and distilled it into two new memory files:

reference_tbx_schema_content.md — the high-value half: the attrib schema (type codes, structure), notes/agents/adornments/aliases, the text/rtfd/html triple storage, links (with a flagged possible doc inconsistency around anchor offsets I haven’t verified), macros, colors, link types, preferences. This is what actually matters for the kind of data work we’ve been doing.
reference_tbx_schema_ui_state.md — window/tab/view configuration. Deliberately kept condensed rather than reproducing every one of the ~60 per-view-type UI attributes (map/chart/crosstabs/gaudi/hyperbolic/table/treemap each have their own private set) — that’s low-value to hold in memory and easy to grep from the source doc if a task ever genuinely needs it.

Updated reference_tbx_ai_doc.md to note the full read is done and point future sessions at the distilled files instead of the source document, and refreshed the index.

One honest caveat carried into memory: I flagged one spot where the doc’s prose looks like it might have a copy-paste error (both sstart and dstart on the link element say offsets reference the “source note’s” text, which seems like it should differ for the destination anchor) — noted as unverified rather than asserted either way, so a future session doesn’t inherit false confidence on that specific point.

Me: So for future work, what would you recommend? Should I ask AI to read the entire document before commencing a task, or have it read the general outline first and then reference the relevant sections as needed?

Claude: My recommendation: don’t read the whole thing upfront – read the short conceptual sections fully, then pull specific element sections on demand right before you write that part of the XML. Here’s the reasoning from what actually happened in this session:

Cost side: The full doc is ~65k tokens. That’s a meaningful slice of a working context window before any actual work happens – every subsequent tool call, file read, and back-and-forth conversation has to share what’s left. Reading it all upfront “just in case” front-loads a cost that mostly doesn’t pay off, since most tasks only touch a handful of elements.

What actually worked well: I read the first ~900 lines fully (Purpose, Terminology, Critical Non-Obvious Behaviours, the full Element Hierarchy outline) – that’s the conceptually load-bearing part, cheap relative to the whole doc, and gave me the map I needed to know where to look later. Then I grepped for specific things (attrib, IsPrototype, DisplayedAttributes) right before writing that piece of XML. That’s roughly a 900/3964-line ratio for a task that touched maybe 4 elements out of dozens documented.

Where it fell short: DisplayedAttributes isn’t explained in the prose at all – grepping for it only surfaced the auto-generated schema dump, not an explanation of its delimiter convention. I inferred the format from a general rule stated elsewhere and got it right, but only confirmed that after the fact by cross-checking against a real example already in the file. The gap wasn’t “I should have read more of the doc” – the doc simply doesn’t cover it – but the lesson is: when I’m inferring rather than reading a direct answer, I should say so at the time, not just proceed silently.

So the practical rule I’d suggest: full read of overview/structural sections once per project (cheap, durable, orients me for everything after), then targeted lookups per element as needed – but for anything higher-stakes (bulk edits, anything touching links between notes, anything where a wrong guess is hard to detect or undo), ask me to read that specific section in full first rather than pattern-match, and call out explicitly when I’m inferring versus quoting the doc directly.

One more thing worth considering: I have a persistent memory system across sessions in this project. I could save the durable facts I’ve now learned (the attrib schema shape, type codes, the proto= serialization rule, the fact that the AppleScript dictionary is undocumented by this file and I had to find Tinderbox.sdef myself) so a future session doesn’t have to rediscover them from scratch. Want me to do that?

mwra · July 19, 2026, 1:49pm

The file was part of a quixotic and unlimitedly unsuccessful quest to get Claude to read and comment on the coherence of aTbRef. The AI can’t read the whole resource—at least not within the context available on a Claude Pro Plan I have no research funding to expand beyond that.

In discussion with Claude it started unequivocally that reading the raw XML was more useful/less wasteful than reading via MCP. Bear in mind we’re talking about reading the whole corpus not just a few note. It then became apparent that understanding general XML syntax is bot the same as understanding the format specific XML structure of a given type of file such as a TBX. So, using my existing aTbRef section (here) and a clean new TBX with at least one of everything that triggers any only-if-used XML data, I worked with Claude—deliberately in Chat mode not Code mode to make the above. Why Chat? This isn’t a coding problem even if the output is written in HTML. The hard graft was reverse-engineering an undocumented^† XML structure and where some data is only present if used. IOW, it is easy to miss things neither I not the AI knew might be there. There are some benign edge cases—re reverse engineering—where the same-named element is used slightly differently in different place. No problem for Tinderbox as it knows the structure: less clear to parsing the structure without inside knowledge.

As well as the HTML page at thread start, the work also produced the TBX posted here.

Were a human or AI to actually read the HTML, the purpose is stated at start:

Purpose provenance and scope

Purpose

This document describes the XML structure of a Tinderbox (.tbx) file. It is intended to give an AI reader sufficient grounding to parse TBX content correctly, interpret XML attribute values accurately, and give well-informed advice to Tinderbox users about document structure and configuration. The syntax described is for version 2 of the TBX schema, as used in v6+ of the Tinderbox app.

Provenance

The document is based on information recorded in the resource "A Tinderbox Reference File" (aTbRef) at https://atbref.com. It is written by Mark Anderson, aTbRef's author in consultation with Tinderbox's designer Mark Bernstein (of Eastgate Systems). The document was generated using Tinderbox v11.7.1b805, at 2026-06-17T00:06:55+01:00.

Scope

The document does not cover Tinderbox's user interface, workflow, or conceptual design. Those are covered in the companion primer documents. This document covers the XML serialisation only.

Indeed, @Estomm’s Claude summary seems to pick this up. I’m slightly surprised at the its comment as to a ‘gap’ re JavaScript and AppleScript as these are self-evidently out of scope, so not fairly a weakness of the resource. Indeed, IIRC, Claude drafted the above so it can’t understand its own writing!

Documenting the JavaScript and AppleScript makes aTbRef’s scope look tiny. But anyone with expertise and lot of spare time for testing could fill that gap (my time is not so free at prresent).

I didn’t, it was the output of 2-3 man-days of effort spread over 2-3 weeks. If you factor in the aTbRef source material, it is years of experience in the mix.

This does seem an interesting use based on one of the key ideas—setting out information is an AI-friendly way that doesn’t waste tokens on aspects that are only desired by human readers.

As it happens I’d already realised this document alone didn’t resolve the original whole-aTbRef consumption problem because Tinderbox uses a link base so inter-note links aren’t harder-coded into notes as they with a wiki, for instance.

The resolution to the last can be seen at A Tinderbox Reference File. The epiphany was Claude observation that whilst there were c2.5 aTbRef HTML pages most of each pages was topic irrelevant (HTML header, body copy headers/footers). The method I used for older experiments to make PDF’s 'printed from a single HTML page hiply uses into one set of HTML stuctural code surrounding the body copy—the letter being the bit we want. After a quick sed call to change inter-HTML-page links to in-page links, we have a functional hypertext in a single HTML page.

This later lessens the context use (tokens) significantly. Even so, Claude’s (genAI’s) inability to sustain multiple parallel contexts—as human can with ease—still limits the AI’s ability to read the corpus. Still, it did result in Claude finding some inconsistencies whilst also throwing light on the shallowness of AI ‘Reading’. Most prompt questions tend to be over-reduced to one or more binary [sic] questions. So, fine for bounded factual errors but less use for broader qualitative.

I note the factual dstart error and have fixed it:
The_XML_TBX_format.html.zip (28.3 KB)

Apart from the above file, the most useful part of the experience was getting a clearer view of generative AI’s inabilities. They don’t devalue what the AI can do fast, accurately and all. But have a views as to its weaknesses has made it easier for me to avoid unhelpful output. I contingent challenge here for the human is genAI’s ability to generate a lot of text without obvious case errors, typos, etc, fools us into thinking it understands things in a human way. It does not!

†. I ought to add that the fact the TBX XML has no public documentation is not an error or omission. There has never been an undertaking to offer that. My older aTbRef notes were a simple fade mecum for the few users who like to, or occasionally needed to, peeked under the hood at file info. It was only Claude insistence that XML was more use than in-app MCP or HTML as an input source in the whole doc/website sense that made me realised so documentation might be useful. The ‘schema’ is my work and any mistakes are mine and Claude’s, not Eastgate’s.

mwra · July 19, 2026, 2:46pm

Updated for one small typo:
The_XML_TBX_format.html.zip (28.3 KB)

Estomm · August 8, 2026, 3:55am

Thank you for this work. Using Claude Code with TBX has sped things up a lot for me.

Claude has some feedback for you:

Claude: It’s more substantial than “nothing else changed” – beyond the dstart fix, there’s a new “Tab and Gallery System” section, a new “XML attribute default values and storage behaviour” section, and the “Critical non-obvious behaviours” section got restructured into definition-list format.

The default-value section is particularly useful: it distinguishes four different meanings of “default” (empty-string / not-stored / not-stored-default-unknown / varies), which is a useful nuance when interpreting TBX files.

mwra · August 8, 2026, 9:15am

Can Claude be a bit more specific as to where the document needs changing. Happy to do so but busy ATM. Referencing to paragraph or line number would help. Claude ought to be able to do this (and ought to without being asked, if comments on a source!)

Estomm · August 8, 2026, 10:46am

Sorry, I may have edited the context away there. Claude isn’t pointing out further changes that need to be made. It has just noticed that you made more changes in the updated document than you advertised, and that they are useful additions.

Estomm · August 8, 2026, 10:50am

Full context if it helps:

Me: You picked up some faults in the Anderson’s work. He made the changes. Can i replace the file. Nothing else changed.

Claude: he fix is confirmed — dstart now correctly says “destination note’s” text element instead of the copy-pasted “source note’s” wording. Good, that’s genuinely resolved.

But this isn’t just that one typo — the diff is 264 lines, not a single-line fix:

Identified which sections changed beyond the dstart fix
It’s more substantial than “nothing else changed” — beyond the dstart fix, there’s a new “Tab and Gallery System” section, a new “XML attribute default values and storage behaviour” section (defining what empty-string vs. not-stored vs. varies actually mean), and the “Critical non-obvious behaviours” section got restructured into definition-list format. Generation timestamp moved from 2026-06-09 to 2026-06-17 — about a week of further work, consistent with Anderson’s “2-3 man-days over 2-3 weeks” description. This is likely the fuller update (dstart fix + content additions), not just the later “one small typo” post.

Worth knowing before I swap it in, but doesn’t change what to do — it’s your file, your download, replacing a reference doc in your own project. Replacing now.

Replace the project reference file with the updated version
Now updating memory: resolving the flagged dstart uncertainty, and folding in the genuinely new content (the attribute-default-value conventions).

Recalled a memory, saved 2 memories
Done. Summary of what happened:

Replaced The_XML_TBX_format.html with the version from ~/Downloads/The XML TBX format.html (found it there once you told me the name — spaces, not underscores, is why my first search missed it).
It was more than “one small typo” — 264 lines of diff, including a fixed dstart/sstart bug (confirming the inconsistency I’d flagged as unverified turned out to be real), plus two genuinely new sections: a “Tab and Gallery System” explainer and an “XML attribute default-value conventions” section that distinguishes four different meanings of “default” (empty-string / not-stored / not-stored-default-unknown / varies) — a real, useful nuance for interpreting any TBX file correctly.
Updated memory accordingly: reference_tbx_schema_content.md now has the resolved dstart note plus the new default-value conventions folded in, and reference_tbx_ai_doc.md records the file swap and why the diff was bigger than expected.
Nice bit of validation on the “flag inferred vs. confirmed instead of guessing” habit — the thing I explicitly declined to assert turned out to be a genuine bug in Anderson’s own document, and he’s since fixed it upstream.