Xtalogten views, three read daily
A mineral inventory app for a two-person business. Each view is one page from its documents. A drawn view says at its top how far behind them it is; a live view is read from them daily.
Data map · the words drawn, the facts read daily

Where data lives

Every place a fact about the business sits when the app is closed: what is in it, who can reach it, whether there is a second copy, and whether getting it back has ever been tried.

loading…

At a glance

How to read a card

there is a copy, or it was tried partly, or by hand only none, never tried, or the sentence needs redrawing nothing to copy or bring back

Second copy asks whether the data exists anywhere else. Getting it back asks whether a restore was ever run, since a copy nobody has loaded is a hope. Today is what the app's own files said at the last daily reading. A sentence in red with “redraw” under it rested on a recorded gap or an open issue that has since closed, so it may no longer be true.

Source: the app's wrangler.jsonc, src/model/schema.ts, migrations/, src/clients/, client/, docs/known-gaps.md and its open issues, read daily; the words on each card are in data-map.json in the guide repository, drawn from the README, the decisions and the gaps. The backup line comes from backups.json, which the app's backup command writes to. This page is public, so it names places and never an id, a person or a figure from the inventory. Everything here is read; nothing is changed, and nothing on this page is read back by the app.
README.md · what it is for

Xtalog: What It Is For

One trustworthy record of every specimen's life, from the moment it is bought from a dealer to the moment its sale is reconciled, so that pricing, re-buying and inventory-health decisions rest on data instead of memory.

Built for a two-person mineral business. The owners are comfortable with spreadsheets and structured data and do not write code, so the documents have to carry the knowledge across a month of not touching a thing.

Live on Cloudflare, behind a sign-in Two inventories loaded: the business stock and a practice copy Does what the one-file app did, and since November finds anything by Lookup and keeps every piece's state Merging a pull request is the deploy

Eight principles

Set in the one-file app's charter in September 2026 and carried into the hosted app.

Lean

Build the smallest thing that removes today's specific pain, then iterate.

One inventory, one database

Every specimen is one row carried through every stage. Reference lists like dealers are their own tables, joined by a key, never copied into the piece.

Near-free infrastructure

No paid platform or service until a named, specific limitation forces it.

Frictionless at the point of work

Buying at a show table, kitchen-table intake, selling at a show: built for speed over completeness. Anything not essential in the moment is deferred, never skipped.

Stable over clever

With no developer on call, every piece must be simple enough to inspect and documented well enough to pick up cold. The gate, the tests and the documents keep it so.

Governed, not rigid

Named fields, controlled boundaries and a change record stop the drift the old spreadsheet suffered, without forcing free text into premature vocabularies.

One term, one meaning

A thing has exactly one name, used identically in conversation, documents, field names and on screen. The glossary holds the names.

A screen's rules are its own

The stages draw the lines between them; they do not dictate how a stage solves its problem inside its line.

The piece's life, and how far the app has got

Five stages, in the order the bar at the top of the app shows them since 12 November. Built stages are what the app does today; the rest each have an issue.

built done outside Xtalog, in the listing tool not built
built

Intake

The lot arrives: dealer, venue, purchase date, lot cost, expected pieces. Batches and pieces are entered, and each piece's permanent UID is issued when its batch is saved. Writing the purchase down at the dealer's table, before the lot, is not built.

issue 57
built

Costing

Spreads the lot cost across its pieces, batch by batch, by an allocation rule. Finish costing fixes it.

built

Labeling

Picks pieces and downloads the label file for the mail merge.

outside Xtalog

Listing

The piece is described, priced and put on a platform; the date and the platform are written on the piece. Today the listing tool writes the description and works the price, and nothing is written on the piece. The price on a piece is a handwritten sticker.

issue 157
not built

Sale

The piece leaves for a price, outside the app, at a show or online. A sales import brings the fact in, and Reconcile ties the price back to the cost, posts profit or loss and sets the piece's state to sold. Which pool a piece sits in, Show or Online, is parked until the first piece goes online.

issue 73

Between stages a piece rests in a state: in stock, listed, sold, or removed with a reason. Since 13 November the app keeps every piece's state; nothing on screen changes it yet. Set apart on the bar's right is Look up, which is not a stage: one box that finds dealers, lots, batches and pieces. Intake and Costing are one screen, with Label information and Costs as two views of the same batch list. Until a lot's costs are finished everything about it stays correctable; UIDs are the one thing that never changes once issued.

What done looks like

Mid term

A piece's full cost-to-price-to-sale path can be rebuilt from the database alone.

Long term

The reconciled record answers the slow questions without anyone reconstructing them by hand:

  • aging inventory
  • hot and cold minerals
  • dealer history
  • realised profit by period
Source: README.md as revised on 13 November 2026 to the bar's five stages. The principles are quoted in the README's own words, shortened; the stage table is the README's, with its issue links.

Xtalog System Context

What you are working with: three places, one change moving through them, and where every rule lives. Drawn from the repository as it stands on 13 November 2026.

Your laptop C:\Xtalog · where work is made and checked GitHub Smikulen/MineralInventoryApp · where work is kept and agreed Cloudflare xtalog · where the app runs MineralInventoryApp checkout the main branch; never edited directly .claude/worktrees/<task> one folder and one branch per change bin/gate → GATE: PASS typecheck · lint · format · 1,901 tests · 41 browser flows localhost app npm run dev, local sign-in bin/db local copy · live backup .dev.vars secrets; Git ignores the file _scratch/<task> throwaway files, outside the repo Claude's memory notes live in your user folder, also outside the repo branch run before a pull request git push Issues · Dependabot alerts the open items; a loose end gets an issue or a known-gaps line Branch + pull request what changed · what to look at · yours to decide Actions: gate.yml runs the very same bin/gate on GitHub's machine Ruleset "Protect main" needs a pull request and a green gate to merge; auto-merge allowed; no force-push, no deleting main the one branch that is live on every push reports pass or fail you click Merge, or auto-merge merge deploys You and your partner, in a browser Cloudflare Access the sign-in in front of everything Worker "xtalog" the API (Hono) and the app in the browser (React) D1 database "xtalog" every inventory: Business and Practice Google Sheet copy built; not switched on yet (needs your Google steps) Workers Builds watches main; branch previews are off Secrets live here too, never in the repo (rule 11) signs in signed-in requests only reads and writes wakes 08:00 UTC deploys the new version
the gate, the one verdict built but not switched on a thing that lives there
The same gate runs twice on purpose: on your laptop before a pull request, and again on GitHub for every push. The ruleset will not let main take a change the GitHub run has not passed; since 12 November a pull request may be set to merge itself once the gate is green, and a branch no longer has to catch up with main first. Writing to the live database from a laptop is possible with bin/db --remote, and that command prints what it will do and asks y/N first; a schema change takes a proven backup of the whole live database before it is applied (13 November).

A change's journey

When a task startsA worktree and a branch are made for it. Main is never touched.Laptop · rule 1
While workingFiles change in the worktree; small commits, pushed early.Laptop → GitHub · rule 3
Before a pull requestbin/gate runs and its last line is the verdict, reported as got.Laptop · rule 2
On the pull requestThree things are told you: what changed, what to look at, what is yours to decide.GitHub · rule 10
On every pushGitHub runs the gate again and shows a tick or a cross on the pull request.GitHub Actions
When you click Merge, or auto-merge firesThe ruleset checks the gate passed, then main takes the change.GitHub ruleset
Minutes laterCloudflare builds main and swaps in the new version. No deploy step by hand.Cloudflare Workers Builds
Every night, once switched onThe Worker copies each inventory to a Google Sheet, only if something changed.Cloudflare cron, 08:00 UTC

Where the rules live

A script enforces it

No prose, because a program says no

  • bin/gate.mjs: the five checks, in order, stop at the first failure.
  • Lint: the three layers stay apart; no function above complexity 15.
  • Tests must cover 90% of the code (set in the test config).
  • .github/workflows/gate.yml: the gate on every push.
  • The GitHub ruleset: pull request plus green gate to reach main.
  • bin/db: asks y/N before writing to the live database; migrate --remote takes a backup first and applies nothing if the backup fails.
CLAUDE.md says it

The sixteen rules no script can check

  • Never work on main; worktree per change.
  • Report the gate result you actually got.
  • Hand back rather than guess.
  • A fact lives in one home.
  • Re-read the diff against the ask.
  • Screens speak your words; feedback is traced before it is fixed.
  • While you are away, only the rarest decisions wait (rule 17).
A doc records it

Decisions, gaps, and what screens are held to

  • docs/decisions/: one dated file per decision; yours to change, and only by a decision.
  • docs/known-gaps.md: deferred on purpose, each with what closes it.
  • docs/rules.md and docs/shapes.md: what holds between the words, and the shape and order of what is not built.
  • docs/interface-guidelines.md: checked before a screen's pull request.
  • README.md: what it is for, running it, deploying.
The glossary names it

One word per thing, in your words

  • GLOSSARY.md: Lot, Batch, Piece and UID, Bulk, Split, lot cost, allocation rule, leftover, Dealer, Venue.
  • The screen and the code say the glossary's words (pull requests 117 and 119).
  • The database columns keep their old names on purpose; the schema file is where the two meet.
  • The verbs and the rules that join the nouns are written down (docs/rules.md, 1 November); the screen words settled since are one small decision each.
Not on this map: the listing tool, which is its own repository and its own Worker, and the old one-file app, which sits in legacy/ as reference only.
CLAUDE.md · read by every session

Xtalog: Working Agreement

Seventeen rules every working session reads before it touches anything. Here they are in plain words, grouped by what they protect.

Where work happens How we know it is right Keep it simple Working with you Outside help

Where work happens

Nothing lands on the live branch by accident, and nothing is lost.

1

Never work on main directly

Every change, even a typo, gets its own branch and folder. Throwaway files go in a scratch folder outside the repo.

3

Durable work lives in GitHub

Commit small and push early. A half-finished branch that is pushed beats a clean one that was lost. A pull request whose decisions are made merges by itself once the gate passes: no session asks whether to merge or to carry on, and you get a list of what merged. Your yes is written on its issue when it is given.

11

Secrets never touch the repo

Not in code, not in config, not in a commit message. They live in a local file Git ignores, and in Cloudflare.

12

Clean up after yourself

A loose end gets a home, an issue or a known-gaps note, or it gets closed. Nothing dangles without a word.

How we know it is right

The evidence, not the summary, is what gets trusted.

2

The gate is the whole verdict

Run it before a pull request and report the result actually got. Claiming it passed without running it is the worst thing a session can do.

9

Re-read the diff against the ask

Before saying done, compare what changed with what you asked for, not with the session's own summary. Sweep every old path when something is replaced.

10

Every pull request tells you three things

What changed, what to look at, and what is yours to decide. Each change says whether it was seen working, covered by a test, or only read. A Words line says which words on screen changed.

Keep it simple

One home per fact, short docs, clean shape, precise names.

5

A fact lives in one home

If a script enforces it, it gets no prose. Else it lives in the rules page. Else in the one doc that owns it. A rule in two places is a bug.

6

Docs are short and plain

Say what a thing is for, not how it is built. A doc that describes code changes with the code; a doc that records a decision changes only by a decision.

7

Three layers, pure core

Models hold shape, services hold thinking, clients hold the outside world. If a test needs a database or a browser, the logic is in the wrong layer.

8

Name things precisely

The glossary is the source of names. Function signatures are documentation. A magic number becomes a named constant with a note saying whether it is a guess or settled.

Working with you

Your words on screen, your call on anything the docs do not settle.

4

Hand back rather than guess

A product question, an ambiguity the docs do not settle, or three failed tries at one fix: stop, say exactly what is needed in plain words, and wait. Never spin.

14

Screens speak your words and keep their promises

On-screen text is your plain phrase, never the team's label. Every screen works by keyboard alone. A caption is a promise: what it leads to is drawn and agreed first.

15

Feedback is traced before it is fixed

Your notes are written back word for word and numbered, and each is sorted by cause before any is called a defect. A decision that seems contradicted is a question for you, not a reversal.

17

When you are away, only the rarest decisions wait

During a scheduled run, or once you have said you are away, a session decides and merges on its own recommendation. Only a money or cost rule, anything that could lose data, the shape of a file that leaves or re-enters the app, and anything that cannot be undone wait for your yes. Screen words are decided and listed for you. When you are here the decisions are yours; merging is not one of them.

Since 2026-11-13

Outside help

Strict on purpose until your revisit on 1 December 2026.

13

Outside code is read before it is trusted

A package or plugin comes in only after its owner, activity and licence are checked and every file that will run is read. Pinned to a version. Stars are hints, not checks.

Revisit 2026-12-01
16

Agents are counted before they are launched

The default is none. One or two helpers run without asking; three or four are announced with a cost estimate; five or more, or any long one, wait for your yes. Each gets its model on purpose: Sonnet to build to an agreed plan, Opus to discover and draw, Fable only when you name it. A session that holds an order of work keeps it moving and comes to you only when blocked or done.

Revisit 2026-12-01

How the page stays short

Where a program can enforce a rule, the program does and the page says nothing: the gate, the layer boundaries, the complexity ceiling, the test coverage floor and the words check are all scripts. The seventeen rules above are the ones no script can check. When the page wants to grow, the question is first whether a script could hold the rule instead.

Source: CLAUDE.md on main as of 13 November 2026. The wording here is a plain-words paraphrase; the page itself is the rule.
GLOSSARY.md · the owner's words

Xtalog Ontology Map

The things Xtalog talks about, how they fit inside one another, and the life a piece lives from the day it arrives to the day it is sold. The nouns are settled, the rules between them and the verbs were written down on 1 November, and on 13 November the app began keeping every piece's state.

settled and built named, not yet built holds the things inside it

The things, and how they nest

An inventory holds lots. A lot holds batches. A batch holds pieces, unless it is bulk.

Account known by the email they sign in with; reaches an inventory through a membership, as owner Inventory a collection of lots; you can hold several and switch between them Lot one purchase, from one dealer, on one day DOUG-2026-001 · lot code 7KQ Dealer Venue Purchase date Lot cost Expected pieces in lot Batches a group entered and costed together · three kinds One piece at a time different pieces, each entered Amethyst on matrix 7KQ-4M Fluorite, cubic 7KQ-4N Pyrite with quartz 7KQ-4P batch ID DOUG-2026-001-B01 Many pieces at once all alike: enter one, give a count Tumbled agate 7KQ-51 Tumbled agate 7KQ-52 … ×12, up to 900 batch ID DOUG-2026-001-B02 Bulk bought by weight: one line, a weight and a cost, no pieces Mixed quartz, 2.4 kg — batch ID DOUG-2026-001-B03 Split parts become new batches, each remembering its parent A piece carries one specimen; bulk is never a piece UID five symbols, 7KQ-4M , never reused Mineral the whole name as written on the card Locality mine · region · province · country Piece cost its share of the lot cost, for life Piece note · Intake ID your private note; your sticker number Label · State the UID's card; in stock, listed, sold or removed
Names are never reissued: a lot ID, a lot code and a UID each stay retired forever, even after a delete, kept in a never-reuse ledger. The example lot and pieces are invented.

The piece's life

Five stages on the bar at the top of the app since 12 November, with Look up set apart on its right. Not every piece walks every stage.

Intake

The lot arrives. Batches and pieces are entered. UIDs are issued.

built

Costing

The lot cost is allocated down to each piece and finished.

built

Labeling

The label file is made and the labels printed.

built

Listing

The piece is described, priced and put on a platform.

not yet built

Sale

The piece leaves for a price, outside the app. The fact comes back in and is reconciled.

not yet built
Between stages a piece rests in a state: in stock listed sold removed, with a reason one state at a time; only a verb moves it, and sold is reached only by Reconcile.

One state at a time, and the verbs that move it

docs/rules.md group 6, decided 1 November; the state, Remove and Return to stock built in the Worker on 13 November, not yet on screen

Intake, or Split a piece starts here List Unlist Reconcile the only way to sold Remove, with a reason Return to stock Delete for mistakes; the record goes in stock listed sold removed with a reason on hand: these two count as what you own
Teal is built, amethyst is named and not yet built, dashed teal is built in the Worker with no screen to press it. Since 13 November every piece carries a state, In stock unless a verb moves it, and Remove and Return to stock work in the Worker, through one function with a test per cell of the state table; nothing on screen can press them yet, so every piece still reads In stock in practice. List, Unlist and Reconcile are still to build. Delete is for mistakes and takes the record away, which no state change ever does. A sold or removed piece keeps its record, its UID, its cost and the date it left.

Cost is a fact. Price is a different word.

Cost is what you paid. It flows down and travels with each piece for life.

Lot costwhat you paid for the whole lot
→
Allocation ruleEvery piece has the same cost · Each piece has its own cost · Cost by each piece's weight
→
Batch costthe share you assign to one batch
→
Piece costthe share that lands on one piece
→
Leftoverthe cents that did not divide evenly stay on the lot, so the books match
Pricewhat the buyer paid, or the asking price. Never the same word as cost; a sale's fees are a fact of their own. Not yet built.

The words that changed on 30 October

Ten decisions, one at a time, and the screen now says them.

Weight only→Bulk
Pull out→Split
Lot price→Lot cost
Cost method→Allocation rule
Total pieces→Expected pieces in lot
Rounding→Leftover
Price locked→Finish costing
Export CSV→Inventory export · Label file
Label code→UID
new words+Dealer · Venue · Mineral · Label design · Remove · Price

The words that changed since, 2 to 13 November

Each its own small decision in docs/decisions/, one at a time.

One cost for all→Every piece has the same cost
A cost for each piece→Each piece has its own cost
A weight for each piece→Cost by each piece's weight
Lot, on the bar→Intake
Start ID→First intake ID
4 labels→2 labels · 4 to print
Nickname (optional)→Nickname, with (optional) in the grey prompt
mineral_inventory_export.csv→Business export 2026-11-13.csv, yours to change
new words+Lot note · Look up · State, kept but not on screen

Three layers caught up, in order

Dictionary first, then the screen, then the code. Each was its own pull request with a before-and-after table.

1

The glossary

Rewritten around the piece's whole life, arrival to sale. Merged 30 October. Pull request 115

2

The screen

Every word on screen and in a message says the glossary's word. 78 files. Merged 1 November. Pull request 117

3

The code

The code's own names say them too: uid, allocationRule, costCents, split. 108 files, eight renamed. Merged 1 November. Pull request 119

–

The database, kept on purpose

Its columns keep their old names. Renaming them means a migration on the live database for nothing a person sees. The schema file is where the two sets of names meet. Yours to reverse.

Codes, and what comes next

How a code is built

7KQ-4M

Three symbols name the lot, two more name the piece. Thirty symbols are allowed: the ten digits and twenty letters. The six letters that look like digits, B, I, L, O, S and Z, are left out, so a code read off a label is never ambiguous.

  • 27,000 possible lot codes
  • 900 UIDs per lot for its whole life, which is why a batch holds at most 900 pieces
  • Typed codes are read with hyphens and spaces removed, in capitals

The rules between the words, written 1 November

The nouns name the things; the rules say what holds between them, so a new fact has a home before anything is built. They live in docs/rules.md in seven groups, each rule marked enforced, decision, not built, gap or first guess, and end with a table of every verb the app does or will do.

  • 37 verbs: 25 built (Remove and Return to stock in the Worker only), 10 not built, 2 gaps
  • A piece has one state at a time, and only a verb moves it; sold comes only from Reconcile
  • After Finish costing no cost on the lot, its batches or its pieces changes
  • Dealer and venue become records of their own, saved at any time, even from a photo of a business card
  • Codes are unique within one inventory; a label photo is read against the inventory you are in
  • Kept for your own collection is treated like gifted, and may return to stock with its cost
  • Lookup finds dealers, lots, batches and pieces from one box (built 13 November)

Decided with the owner on issue 98. Still open: a split that remembers its parent, bulk split into bulk, and the owner's personal collection (issue 123). What is not built has its shape and its order in docs/shapes.md: dealer and venue records, Reconcile by hand with profit, the sales import, Save a card, Listing, and label photos at the point of sale.

Source: GLOSSARY.md, docs/rules.md, docs/shapes.md and docs/decisions/ on main as of 13 November 2026. Entries the app does not act on yet are marked not yet built there, and in amethyst here.
package.json · wrangler.jsonc · the two repositories

Xtalog Tech Stack

Two small apps on one platform. Xtalog keeps the inventory; the listing tool writes eBay listings and checks prices with Claude. Both run on Cloudflare, both live in GitHub, and both were built with Claude Code.

Xtalog, the inventory the listing tool Claude planned, not built

Two apps, one platform

What talks to what when you use them.

Cloudflare Workers run the code at the edge · D1 is the database · Access is the sign-in · a merge to main deploys You, in a browser laptop or phone You, in a browser often the phone, at the kitchen table or a show Xtalog the inventory · one Worker, one database holding every inventory Cloudflare Access the sign-in; the app never sees a password The app in the browser React 19 · React Router 8 · built by Vite The Worker: the API Hono 4 routes · Zod 4 checks every request · jose checks the Access token · TypeScript throughout D1 database "xtalog" SQLite at the edge · Drizzle ORM · migrations Google Sheet copy cron 08:00 UTC · Sheets API · not switched on signs in once JSON over /api reads and writes nightly, only on a change The listing tool eBay listings and price checks · one Worker, no database One listing page, no build step piece, market check, description, price card · photos shrunk in the browser, never kept The Worker: passcode, then two separate calls to Claude plain JavaScript · Anthropic SDK · the key is a Cloudflare secret, never in the repo Claude, through the Anthropic API model claude-opus-5-5 · the writer: title, description, two blocks from the notes the market check: a web search on Anthropic's side, then a memo with evidence one notes box, up to three photos with the passcode photos, notes, the prompt GitHub: two private repositories a pull request per change · the gate runs on every push · merging to main deploys Claude Code: how both were built sessions that read CLAUDE.md, the glossary and the rules, run the gate, open the pull request
The two apps do not talk to each other yet. The piece's UID goes from a label into the listing tool's notes by hand, and comes back in the listing. The planned bridge is a sales import: a spreadsheet from the listing tool, or a photo of labels at the point of sale, read into Xtalog and reconciled. Beyond that the owner means to bring the listing tool into Xtalog as one application (issue 157); its questions are settled after the eBay run of 14 and 15 November.

Xtalog, layer by layer

Models hold shape, services hold thinking, clients hold the outside world. Versions as pinned on 13 November 2026.

In the browser

React 19

  • React Router 8 for the pages
  • Built and served by Vite with the Cloudflare plugin
  • May use the models and services, never the routes or clients
The API

Hono 4 on a Worker

  • Zod 4 validates every request and reply shape
  • Routes are wiring; the thinking is in pure service functions
  • TypeScript end to end, one type system for both sides
The data

Cloudflare D1

  • SQLite at the edge, one database for every inventory
  • Drizzle ORM; the schema file is the one source of the tables
  • Migrations generated by Drizzle Kit, applied with bin/db
Sign-in

Cloudflare Access

  • Access shows its own sign-in page in front of everything
  • The Worker checks the signed token with jose and trusts only the email it vouches for
  • Locally a single email in .dev.vars counts as signed in
The backup

Google Sheets API

  • Every inventory to one tab, nightly, only on a change
  • Needs a service account key as a Cloudflare secret
  • Built; waiting on the owner's Google steps
The checks

The gate, five tools

  • TypeScript typecheck · ESLint with the layer and complexity rules · Prettier
  • Vitest, 1,901 tests, 90% coverage floor
  • Playwright, 41 flows in a real browser

The listing tool, layer by layer

Deliberately smaller: plain files, no framework, no database.

In the browser

One listing page

  • At /: the piece, an optional market check, the description with its locality and assemblage blocks, the price card
  • The older writer at /writer and price check at /price still work, no longer linked
  • Photos are shrunk in the browser and never stored anywhere
The arithmetic

The price card, from the eBay calculator

  • Pure JavaScript the page loads as a module, with its own tests
  • Two modes, Set my margin and Set what I pocket, and a table of the price to list at for no discount, 10, 20 and 30% off
  • Its defaults and the shipping choice are first guesses, yours to settle (issues 161 and 162)
The Worker

Plain JavaScript, no build step

  • A shared passcode, compared without leaking timing
  • Anthropic SDK for both calls; the key is a Cloudflare secret
  • One automatic retry for the writer; tests with Node's own runner
Deploy

Wrangler

  • One command deploys the Worker and its pages
  • Live at a workers.dev address
  • Small style and prompt tweaks go live by standing approval

Where Claude is in the picture

Three different roles, and it helps to keep them apart.

at run time

Inside the listing tool

Two separate calls, two separate prompts, neither runs the other. The writer turns photos and a free-text notes box into an eBay title and description, drafts a locality block and an assemblage block, picks the UID and the cost out of the notes, and answers follow-ups. The market check reads the same notes, searches the web on Anthropic's side, and writes a memo with a price range and the evidence; one folded line says what the check cost. The photos decide which tier runs.

Model: claude-opus-5-5. Cost per call is counted from Anthropic's price list, copied into the code with its date.

at build time

Claude Code, building both apps

Every session reads the rules page, the glossary and the rules between the words before it touches anything. It works in a worktree, runs the gate, opens a pull request that says what changed, what to look at and what is yours to decide, and records what it learned in a memory that persists between sessions. A cap on helper agents is rule 16. Since 13 November, rule 17: while you are away a session decides and merges on its own recommendation, and only the rarest decisions wait.

Xtalog's own code makes no call to Claude today.

planned

Inside Xtalog, later

  • A photo of labels at the point of sale, read by AI into sale lines, then reconciled
  • A photo of a dealer's business card on the phone, read by AI, checked by you
  • Business questions answered by AI reading the pieces' names and figures, with rules you set
  • Reusable description blocks per locality and per mineral, shared with the listing tool
  • The listing tool itself, brought into Xtalog as one application (issue 157)

The repositories, and what it costs to run

Repository What it holds Where it runs Visibility
MineralInventoryApp Xtalog, its tests, its governing documents and the old one-file app as reference Cloudflare Worker + D1, behind Access private
listing-app The listing tool: the listing page, two older pages, the Worker, the prompts, the price arithmetic Cloudflare Worker at a workers.dev address, behind a passcode private
ebaycalc The eBay fee calculator as it was before it moved into the listing tool Nowhere now; kept as the record public
xtalog-guide These nine views, one file, and the daily status file GitHub Pages private repo, public page
Cloudflare

Free tiers today

Workers, D1 and Access all sit inside Cloudflare's free allowances at this size. The principle is near-free infrastructure: no paid service until a named limitation forces it.

GitHub

Pro, $4 a month

Private repositories, Pages from a private repository, and the included Actions minutes that the gate runs against.

Anthropic

Pay per call

The listing tool pays for each writer call and each market check by the tokens used and the searches made. Nothing in Xtalog itself is metered.

Source: the two repositories' package.json and wrangler.jsonc, the README of each, and docs/rules.md, on main as of 13 November 2026. Version numbers are the pinned ones at that date.
src/model/schema.ts · where each thing is stored

Xtalog Data Model

The twelve tables in the database, the keys that tie them together, and the conventions every number and date follows. The ontology map shows the ideas; this page shows the shelves they sit on.

the nesting spine sign-in bookkeeping primary key, the row's own identity points at another table unique within its parent

The twelve tables

an arrow runs from the many to the one they belong to

inventory_id lot_id batch_id account_id inventory_id inventory_id piece_id account 4 cols id text email text name text created_at text no passwords: Access vouches for the email membership 4 cols inventory_id text account_id text role owner created_at text key: inventory_id + account_id inventory 3 cols id text name text created_at text lot 16 cols id uuid number DOUG-2026-001 inventory_id text code text dealer text acquisition_venue text purchase_date text price_cents int piece_count int +7 more, incl. includes_bulk, price_locked_at unique in the inventory: code, number batch 13 cols id uuid lot_id text seq int name text kind single · group · bulk label_size small · regular weight_mg int cost_cents int cost_method text +4 more, incl. weight_unit, costs_saved_at unique in the lot: seq · ID shown = number + B + seq piece 27 cols id uuid batch_id text seq int mineral text mine text region text country text label_note text record_note private weight_mg int cost_cents int label_code the UID +15 more, incl. province_state, state, left_on three legacy_* columns kept exactly as imported label_code_registry 3 cols inventory_id text code text lot_number text key: inventory_id + code lot_number names the lot; no key, outlives it lot_code_registry 3 cols inventory_id text code text lot_number text key: inventory_id + code lot_number names the lot; no key, outlives it retired_lot_id 2 cols inventory_id text lot_number text key: inventory_id + lot_number a series number is never reissued reference_value 5 cols inventory_id text field 9 names value text count int last_used date key: inventory_id + field + value label_list_item 4 cols inventory_id text position int piece_id text count 1…999 key: inventory_id + position backup_state 3 cols key text value text updated_at text belongs to no inventory
Read down the middle: an inventory holds lots, a lot holds batches, a batch holds pieces. A person reaches an inventory only through a membership row. Everything on the right carries the inventory's key and goes when the inventory goes, except the backup state, which belongs to the app as a whole. The three registries remember a lot by its number, not its key, so they outlive the lot on purpose.

Two sets of names meet here

the columns kept their old names when the code took the glossary's words

Column in the databaseName in the codeWhat the owner sees
piece.label_codeuidUID
label_code_registryuidRegistrynever shown
lot.price_centscostCentsthe lot's cost
lot.piece_countexpectedPiecespieces expected
lot.price_locked_atcostingFinishedAtFinish costing
lot.rounding_centsleftoverCentsthe leftover cents
batch.cost_methodallocationRuleAllocation rule
lot.numberlotIdthe lot ID
batch.namenicknameNickname
piece.record_notepieceNotethe piece note
piece.entry_timestampenteredAtnever shown
label_list_item.countcopiescopies

Decided 1 November 2026, and carried through the naming sweep to 13 November: renaming a column buys nothing a person sees, so the schema file is the one place where the two sets of names are matched up. Every other file uses the code's name. The export file and the backup sheet keep the old app's column names on purpose, a format the importer reads back in.

How a value is written down

six conventions that hold in every table

Money is whole centsprice_cents = 12500

Never dollars with a decimal point, so no sum is ever off by a rounding error.

Weight is whole milligramsweight_mg = 48200 · weight_unit = g

Stored one way; the unit the owner typed is kept beside it for showing back.

Time is text2026-11-01T13:26:55Z

Every instant and date is an ISO string, so it reads the same in the database, the API and the export.

Keys are private, IDs are humanid = uuid · number = DOUG-2026-001

The key the database uses is never shown. The lot ID and the five-character UID are what people read.

Choices are closed listskind = single · group · bulk

Label size, weight unit, batch kind, the allocation rule, the role, and since 13 November a piece's state and its remove reason each take one word from a short list; the database refuses any other.

Empty is a blank, not a holedealer = ""

Text fields default to an empty string. Only a number can be missing, and a missing cost is not a cost of zero.

What a delete takes with it

and what it never touches

Goes together

  • Delete an inventory and its memberships, lots, batches, pieces, registries, typeahead lists and label list go with it.
  • Delete a lot and its batches and their pieces go with it.
  • Delete a batch and its pieces go with it.
  • Delete a piece and its rows in the label list go with it.
  • Delete an account and its memberships go; the inventories stay.

Kept on purpose

  • Every UID ever issued stays in the registry, so no piece ever gets a code another piece once had.
  • Every lot code ever reserved stays, for the same reason.
  • A deleted lot's number is written to the retired list, so its series number is never reissued.
  • The three legacy columns on a piece are never edited; they hold what the one-file app recorded.
  • A removed piece is not deleted: it keeps its row, its UID and its cost, with its state, its reason and the day it left.

Five migrations so far

each one a file in migrations/, applied in order and never edited after

  1. 0000Initial

    The tables as designed: inventory, lot, batch, piece, the registries, the typeahead lists and the label list, with the sign-in library's own tables beside them.

  2. 0001Cloudflare Access

    Sign-in moves out of the app. The password tables are dropped; account becomes the app's own list of people, filled from the old user rows.

  3. 0002Internal keys

    Lot and batch keys become private uuids, so two inventories can each hold a lot called DOUG-2026-001. The human lot ID moves to its own column.

  4. 0003Backup state

    One small table so the nightly Google Sheet copy can tell whether anything changed since last time.

  5. 0004Piece state

    Three columns on the piece: its state (every piece that existed became In stock), the remove reason and the day it left. The database refuses a fifth state or a sixth reason. Applied to the live database on 13 November, after the first proven backup of it.

Source: src/model/schema.ts, migrations/ and docs/decisions/ on main as of 13 November 2026. The drawing shows the key columns of each table and says how many it leaves out; the schema file is the whole truth.
Sequence diagram · PUT /api/batches/{id}

What happens when you press Save

One save of a batch, followed from your keyboard to the database and back, across the five parties that handle it. Read top to bottom; time runs down the page.

a call the reply 401 where the request can stop instead, and the code it answers with

Sixteen steps, one request

every step is a line in the code on main

Your screen client/ Cloudflare Access in front of the Worker The route src/routes/batches.ts The thinking src/service/ The database D1, through src/clients/db.ts You press Save the screen builds the body: rows, nickname, size, weight, and since 13 November the costs too 1 PUT /api/batches/{id} JSON body · header X-Inventory-Id 2 Checks you are signed in not signed in: the sign-in page; the Worker never sees it 3 sign-in page forwards, with Cf-Access-Jwt-Assertion that token is the app's whole session 4 requireSession verifies the token (jose) · finds your account by email the inventory must be one of yours 5 401 · 403 validateJson(updateBatchSchema) Zod checks the body's shape 6 400 findBatch the batch must be in your inventory 7 404 the batch and its pieces 8 plan the rows which cells changed, which rows are new or gone · intake IDs UIDs for new rows · today's date · In stock for new pieces 9 a plan of statements, or a refusal with a sentence 10 4xx runBatch: one batch of statements update the batch · insert, update, delete pieces · register UIDs prune the label list · update the typeahead lists 11 all written, or nothing 12 500 200 · the batch and its pieces 13 GET /api/inventory after every save the screen reloads the whole inventory 14 the snapshot 15 Redraw focus lands where the plan said · a notice if there is one 16
The save is one request and one database batch: either every statement in step 11 is written or none is. Access decides who gets in; the route decides whether the request makes sense and which rows change; the service does the thinking without touching the database; the database client is the one place the database is opened.

The three layers, on this one request

rule 7 of the working agreement, seen working

Steps 1, 2, 14, 16The screenclient/batches/useLifecycle.tsx · client/api.ts

Builds the request, sends it, reloads the inventory after, and puts focus where the plan said. Never talks to the database.

Steps 5, 6, 7, 11, 13The routesrc/routes/batches.ts · src/routes/_shared.ts

Wiring, not thinking: checks the session and the body, finds the batch, runs the plan's statements, answers JSON.

Step 9The thinkingsrc/service/intakeIds.ts · lotIds.ts · dates.ts · pieceState.ts · split.ts

Pure functions: take models, return models. The tests here need no database and no browser.

Steps 3, 4, 7, 11The outside worldsrc/clients/access.ts · src/clients/db.ts

One thin file per outside system: Access's token check, and Drizzle on D1, opened fresh for every request.

Honest noteNot all the thinking has moved yetissue 207, open

Today the planning of rows still sits inside the route file (about 720 lines) next to the wiring; the state rules, the split and the cost shares already live in services. Pull request 116, which moved the rest, was closed stale on 13 November; issue 207 is the redo.

Where it can stop

every exit answers with a sentence the screen shows as it is

sign-in pageCloudflare Access

Not signed in. The Worker never sees the request.

401Sign in first.

The token is missing or does not verify.

403That inventory is not yours.

The header names an inventory you are not a member of.

400The request was not understood…

The body's shape is wrong; the sentence names the field.

404Not found.

No such batch in your inventory.

4xxOnly 3 codes left; this needs 5.

A refusal from the plan: the rules said no, with the reason.

500Something went wrong on the server. Nothing was changed; try again.

The batch did not write. True by construction: it is all or nothing.

What proves it

all of it runs inside the gate, on your laptop and again on GitHub

50route tests

src/routes/batches.test.ts: every exit and every kind of save, against a real SQLite.

45screen tests

The batch screen's flows and section, with the API stubbed: focus, notices, redraw.

2browser flows

"Make a batch of two pieces, save it, see the UIDs, edit it and save again", and the grey typeahead letters, in Playwright.

Four facts worth keeping

All or nothing

One save is one database batch. A failure half-way leaves nothing changed.

No session of its own

The app keeps no cookie and no password. Access's token, checked on every request, is the session.

Fresh every time

The database is opened per request. There is no connection to keep alive and nothing to leak between people.

Reload after every save

The screen fetches the whole inventory again. Simple, and why two people editing one lot can overwrite each other (a known gap).

Source: client/, src/routes/, src/service/, src/clients/ and tests/ on main as of 13 November 2026, traced by reading. Step counts are the test files' own; the gate runs every one of them.
docs/roadmap.md · README.md · GitHub Issues · docs/known-gaps.md · docs/decisions/ · read daily

Roadmap and decisions

Where Xtalog is going and in what order, what waits on the owner, and what is deferred on purpose. No line here is typed by hand: each is read from the app's documents and from GitHub every day.

loading…

The horizon

How far the piece's life is built

the README's five stages

The order

the owner's to change; a finished row is deleted from the page

Alongside, not a row

The owner's queue

issues labelled “your call”, oldest first

Issues with no kind label

counted in none of the numbers on this page until they are labelled

Known gaps

deferred on purpose, each with what closes it

The latest decisions

Source: docs/roadmap.md, the stage table in README.md, docs/known-gaps.md and docs/decisions/ on the app's main branch, and its open issues on GitHub, read daily by scripts/collect-status.mjs. The gaps are sorted by a first guess: whether the sentence that closes a gap names the owner or a decision. Everything here is read; nothing is changed, and nothing on this page is read back by the app.
Engineering dashboard · refreshed daily by the Status workflow

Build health

The one view that changes on its own. Nine numbers that say whether the app is up, whether the last change passed, and what is waiting on whom.

loading…

Is it healthy

What is waiting

Open pull requests

age, and whether their gate is green

Code merged without a doc

in the last 30 days

Source: status.json beside this page, written by scripts/collect-status.mjs in the guide repository. It runs at 2 am Central every day and whenever the Status workflow is run by hand. Everything here is read; nothing is changed.