paneltir 0.9.0 → 0.10.0

package/CLAUDE_MD_SNIPPET.md

@@ -31,6 +31,13 @@ library shared with other projects. Rules:
   src/dashboard-theme.ts -->. Colour changes go there, never in the kit. The
   dashboard's **shape** is a `DashboardThemeForm` passed to the same provider
   (`panel` or `ledger`); it too is this project's choice, not the kit's.
+- **This project's theme goes to `PanelApp` as `extraThemes`, never as
+  `themes`.** `extraThemes` offers it alongside the four the kit ships;
+  `themes` means "exactly these and nothing else", so passing one theme there
+  deletes all four and the settings sheet ends up with a single row. That is
+  not hypothetical — it happened to two projects before the distinction
+  existed, and it looks like the kit having no themes rather than like a prop
+  being wrong.
 - **The panel's gate is this project's, not the library's.** `middleware.ts`,
   `lib/session.ts` and `api/login.ts` / `api/logout.ts` / `api/panel-state.ts`
   were copied here by `npx paneltir init`. They hold this project's password
@@ -38,6 +45,13 @@ library shared with other projects. Rules:
   change when the kit updates, and `paneltir init` will not overwrite them.
   The password, the GitHub token and the target repository are environment
   variables where this project is hosted — never in this repository.
+- **Those copied files do not update, so they have to be asked.** Run
+  `npx paneltir doctor` when the panel misbehaves for no visible reason: it
+  compares each copied file against the version installed now and separates
+  the three answers that need different actions — you edited it, the template
+  moved underneath you, or both. The second is the one no `git diff` can find,
+  because there is nothing in this project's history to diff against, and it is
+  how a fix released upstream stayed out of a project for two releases.
 - **The panel explains itself once.** New readers get a short guided tour the
   first time they open the board; each note is dismissed and stays dismissed.
   **Help** in the header reports what the panel needs — the password, the

package/INSTALL.md

@@ -19,7 +19,7 @@ identity** — never another project's.
    npm install paneltir
 
    # or, without npm access, straight from the repository:
-   # npm install github:daifukus/paneltir#v0.9.0
+   # npm install github:daifukus/paneltir#v0.10.0
    ```
 
    (Use the tag you were given; never install without pinning a version.)
@@ -165,6 +165,7 @@ identity** — never another project's.
    | `extraThemes` | This project's own identities, offered **as well as** the kit's presets. Theirs come first, so the panel opens in one of them. This is the one you want. |
    | `themes` | The exact set: these and nothing else, presets included. Only for a caller deliberately curating the list — it replaces rather than adds. |
    | `defaultTheme` | Which one to draw before the board has said. Defaults to the first key. |
+   | `gate` | `.paneltir/gate.json` from this project, imported. With it the setup list gains a row saying whether the files `init` copied are still the ones this version ships; without it the panel says nothing about them rather than guessing. |
    | `brand` | What sits where a name goes in the header. Defaults to the board's `project`. |
    | `capabilities`, `extras` | Sections of the caller's own. Not drawn when absent. |
    | `links`, `footer`, `decoration`, `className` | Where else to go, what sits under the panel, and anything the caller draws behind it. |
@@ -192,6 +193,38 @@ identity** — never another project's.
    there. On a board already in use the same walkthrough is behind **Help**,
    offered only while something is actually missing.
 
+   **The files `init` copied do not update, so ask them.** Everything under
+   `api/`, `lib/` and `middleware.ts` is this project's from the moment it is
+   copied — that is the point, since it holds this project's password rule —
+   and the cost is that a fix released upstream can be missing here while every
+   version number on screen looks current. It has happened: the `HTTP 500` on
+   saving was fixed in `template/api/panel-state.ts`, and projects installed
+   before that still had it.
+
+   ```bash
+   npx paneltir doctor
+   ```
+
+   **Commit `.paneltir/gate.json`.** `init` writes it to record what it copied
+   and what it copied it from, and it is provenance rather than a build
+   artifact: ignored by git it disappears on the next clone and every answer
+   below degrades to "differs", which is the one that cannot say who moved.
+
+   It separates the three answers that need different actions — *yours* (you
+   edited it), *BEHIND* (you did not touch it and the template moved), *BOTH* —
+   and the middle one is invisible to `git diff`, because this project's history
+   has nothing to compare against. `init --force` replaces the gate and never
+   the board; read the diff first where a file is marked BOTH, or the edit is
+   lost.
+
+   ```bash
+   npx paneltir run "what this pass did" --cards=a,b
+   ```
+
+   appends an entry to the board's `runs` so the record does not depend on
+   anyone remembering at the end of a session. It writes the file and commits
+   nothing.
+
    Two things to check before trusting it: `/admin` signed out must land on
    `/login`, and **the panel's own JavaScript bundle must answer 401 signed
    out**. If it does not, point the last entry of the matcher in
@@ -204,7 +237,7 @@ identity** — never another project's.
 
    ```bash
    npx paneltir version          # version, fingerprint, where it came from
-   npx paneltir check 0.9.0      # exits non-zero if that is not what is installed
+   npx paneltir check 0.10.0      # exits non-zero if that is not what is installed
    npx paneltir board            # read the board and say what is wrong with it
    ```
 

package/README.md

@@ -54,7 +54,7 @@ tag rather than a branch, so an unfinished push cannot reach a project:
 npm install paneltir
 
 # or, without npm access, straight from the repository:
-# npm install github:daifukus/paneltir#v0.9.0
+# npm install github:daifukus/paneltir#v0.10.0
 ```
 
 Installing from Git runs the `prepare` script, which builds `dist/`, so the

package/bin/paneltir.mjs

@@ -14,7 +14,8 @@
  * to the project: readable, editable, in its own git history. Re-running never
  * overwrites what is already there.
  */
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
@@ -110,6 +111,43 @@ function survey(target) {
   return found
 }
 
+/**
+ * Records the provenance of the gate now in the project.
+ *
+ * Merged rather than replaced: re-running `init` writes only the files that
+ * were missing, so a stamp that dropped the rest would forget where the
+ * majority of the gate came from. Only files this run actually wrote are
+ * re-stamped — for one it left alone we did not write it and cannot claim to
+ * know its origin, so the previous answer stands or there is none.
+ *
+ * The board is stamped like the rest and then deliberately ignored by
+ * `doctor`: it is meant to diverge from the seed on the first card, and a
+ * report that called that drift would be noise on every project that is
+ * working.
+ */
+function writeStamp(target, templateFiles, written) {
+  const previous = readStamp(target)
+  const files = { ...(previous?.files ?? {}) }
+  for (const file of written) files[file] = sha256(join(target, file))
+
+  const stamp = {
+    version: pkg.version,
+    templateHash: fingerprint.templateHash ?? '',
+    copiedAt: new Date().toISOString(),
+    files,
+  }
+  try {
+    mkdirSync(dirname(join(target, STAMP)), { recursive: true })
+    writeFileSync(join(target, STAMP), JSON.stringify(stamp, null, 2) + '\n')
+  } catch (error) {
+    // Never fatal. The gate is copied and working; the stamp only makes a
+    // later report sharper, and failing the install over bookkeeping would
+    // trade something that matters for something that does not.
+    console.error(`\npaneltir: could not write ${STAMP} (${error.message}).`)
+    console.error('The gate is in place; `paneltir doctor` will have less to go on.')
+  }
+}
+
 function reportSurvey(found) {
   const lines = []
 
@@ -149,6 +187,36 @@ Remove it once the board is moved over, or the project ships both.`)
 /** The board. Never replaced once it exists — see the loop below. */
 const BOARD_SEED = 'src/data/panel-state.json'
 
+/**
+ * Where `init` records what it copied and what it copied it from.
+ *
+ * The gate is the one part of this package that leaves as files a project
+ * keeps, and a kept file can never be told it is old. That has been paid for
+ * twice: the `HTTP 500` fix landed in `template/api/panel-state.ts`, so every
+ * project installed before it still has a save that cannot work, and the skill
+ * file is copied the same way, so a rule learned upstream never reaches the
+ * Claude that reads it.
+ *
+ * A plain diff cannot close that, because it cannot tell "you edited this"
+ * from "we changed this underneath you" — and those need opposite actions.
+ * Hashing each file as written is what separates them.
+ */
+const STAMP = '.paneltir/gate.json'
+
+function sha256(path) {
+  return createHash('sha256').update(readFileSync(path)).digest('hex')
+}
+
+function readStamp(target) {
+  try {
+    return JSON.parse(readFileSync(join(target, STAMP), 'utf8'))
+  } catch {
+    // Absent or unreadable is not a fault: every project installed before
+    // stamping existed is here, and `doctor` still compares the files.
+    return null
+  }
+}
+
 function init(args) {
   const force = args.includes('--force')
   const target = process.cwd()
@@ -180,6 +248,8 @@ function init(args) {
     written.push(file)
   }
 
+  writeStamp(target, files, written);
+
   console.log(`paneltir ${pkg.version} — the panel's gate, into ${target}\n`)
 
   const notes = reportSurvey(survey(target))
@@ -299,7 +369,7 @@ function check(args) {
  * neither helps the person who has just edited the file by hand and wants to
  * know before they push. This is that answer, from the same check.
  */
-function board(args) {
+async function board(args) {
   const file = args.find((a) => !a.startsWith('-')) || process.env.PANEL_FILE || 'src/data/panel-state.json'
   const path = resolve(process.cwd(), file)
 
@@ -309,7 +379,7 @@ function board(args) {
     process.exit(1)
   }
 
-  const check = readBoard(readFileSync(path, 'utf8'))
+  const check = (await boardReader())(readFileSync(path, 'utf8'))
   if (check.ok) {
     const cards = check.board.cards.length
     console.log(`ok  ${file} — ${cards} card${cards === 1 ? '' : 's'}, ${check.board.columns.length} columns`)
@@ -328,7 +398,205 @@ function board(args) {
   process.exit(1)
 }
 
-const { readBoard } = await import(pathToFileURL(join(here, '../dist/index.js')).href)
+
+/**
+ * Says whether the files this project copied are still the files it shipped.
+ *
+ * The three answers it exists to tell apart:
+ *
+ *   - **yours** — you edited it. Nothing to do; the gate is meant to be edited,
+ *     and this is only here so the next line is believable.
+ *   - **behind** — you did not touch it and the template moved. This is the one
+ *     that has cost real money twice, and the one a bare `git diff` cannot see
+ *     at all, because there is nothing in the project's history to diff
+ *     against.
+ *   - **both** — you edited it *and* the template moved. The only case that
+ *     needs a person: `--force` would throw your edit away.
+ *
+ * It reports and never repairs, for the same reason the panel records a request
+ * instead of running it: replacing somebody's front door is a decision, and
+ * `init --force` is where a person makes it having read what changed.
+ */
+function doctor() {
+  const target = process.cwd()
+  const templateDir = join(packageRoot, 'template')
+  if (!existsSync(templateDir)) {
+    console.error('paneltir: this install has no template/ directory.')
+    process.exit(1)
+  }
+
+  const stamp = readStamp(target)
+  const files = walk(templateDir).sort()
+
+  console.log(`paneltir ${pkg.version} — the gate in ${target}\n`)
+
+  if (!stamp) {
+    console.log(`No ${STAMP}, so this gate was copied before stamping existed.`)
+    console.log('Files can still be compared; "you edited it" and "we changed it"')
+    console.log('cannot be told apart until the next `init` writes one.\n')
+  } else {
+    const behind = stamp.templateHash !== (fingerprint.templateHash ?? '')
+    console.log(`Copied from v${stamp.version} on ${String(stamp.copiedAt).slice(0, 10)}`)
+    console.log(behind ? 'The template has changed since.\n' : 'The template has not changed since.\n')
+  }
+
+  const rows = []
+  for (const file of files) {
+    // The board is meant to diverge: it stops being a template on the first
+    // card. Calling that drift would put a warning on every working project.
+    if (file === BOARD_SEED) {
+      rows.push([file, existsSync(join(target, file)) ? 'yours' : 'missing', 'the board — never compared'])
+      continue
+    }
+
+    const here = join(target, file)
+    if (!existsSync(here)) {
+      rows.push([file, 'missing', 'never copied; `paneltir init` writes it'])
+      continue
+    }
+
+    const mine = sha256(here)
+    const theirs = sha256(join(templateDir, file))
+    const stamped = stamp?.files?.[file]
+
+    if (mine === theirs) {
+      rows.push([file, 'current', ''])
+    } else if (!stamped) {
+      rows.push([file, 'differs', 'no stamp, so who moved cannot be said'])
+    } else if (mine === stamped) {
+      rows.push([file, 'BEHIND', 'you did not touch it; the template moved'])
+    } else if (stamped === theirs) {
+      rows.push([file, 'yours', 'you edited it; the template has not moved'])
+    } else {
+      rows.push([file, 'BOTH', 'you edited it AND the template moved — read both'])
+    }
+  }
+
+  const width = Math.max(...rows.map(([file]) => file.length))
+  for (const [file, state, note] of rows) {
+    console.log(`  ${state.padEnd(8)} ${file.padEnd(width)}${note ? `  ${note}` : ''}`)
+  }
+
+  const stale = rows.filter(([, state]) => state === 'BEHIND' || state === 'BOTH')
+  const missing = rows.filter(([, state]) => state === 'missing')
+
+  if (!stale.length && !missing.length) {
+    console.log('\nNothing to do.')
+    return
+  }
+
+  if (stale.length) {
+    console.log(`\n${stale.length} file(s) are older than the package they came from.`)
+    console.log('See what changed, then decide:')
+    console.log(`  diff -u <file> node_modules/paneltir/template/<file>`)
+    console.log('`paneltir init --force` replaces the gate and never the board.')
+    console.log('Anything marked BOTH would lose your edit — read that diff first.')
+  }
+  if (missing.length) {
+    console.log(`\n${missing.length} file(s) were never copied. \`paneltir init\` writes them.`)
+  }
+  // A gate that cannot work is a failure, not a remark: this runs in CI for
+  // some projects, and an exit code is the only part of it a script reads.
+  process.exit(1)
+}
+
+/**
+ * Appends a run to the board, so the record does not depend on remembering.
+ *
+ * `runs` is what each pass actually did, and until now it was written by hand
+ * — by Claude, into JSON, at the end of a session, from memory. That is the
+ * shape of record that is complete right up until the session that mattered.
+ * A command can be called the moment the work lands.
+ *
+ * It writes the file and nothing else: the board is committed by the panel's
+ * Save or by the project's own commit, and a CLI that pushed on somebody's
+ * behalf would be the second thing in this project writing to their
+ * repository.
+ */
+async function run(args) {
+  const flags = args.filter((a) => a.startsWith('--'))
+  const plain = args.filter((a) => !a.startsWith('--'))
+  const summary = plain[0]
+  const file = plain[1] ?? BOARD_SEED
+
+  if (!summary) {
+    console.error('paneltir run "what this pass did" [--cards a,b] [--by you] [board.json]')
+    process.exit(1)
+  }
+
+  const path = resolve(process.cwd(), file)
+  if (!existsSync(path)) {
+    console.error(`paneltir: no board at ${file}`)
+    process.exit(1)
+  }
+
+  const text = readFileSync(path, 'utf8')
+  const check = (await boardReader())(text)
+  if (!check.ok) {
+    // Refused before writing, not after: appending to a board that is already
+    // broken buries the fault under a change nobody asked for.
+    console.error(`paneltir: ${file} is not a board this kit can read, so nothing was appended.\n`)
+    for (const problem of check.problems) {
+      console.error(problem.at ? `  ${problem.at}\n    ${problem.says}` : `  ${problem.says}`)
+    }
+    process.exit(1)
+  }
+
+  const board = check.board
+  const cards = (flags.find((f) => f.startsWith('--cards='))?.slice(8) ?? '')
+    .split(',')
+    .map((id) => id.trim())
+    .filter(Boolean)
+
+  // A run naming a card the board does not have is a claim that cannot be
+  // checked, which is the only thing `cards` was for.
+  const known = new Set(board.cards.map((card) => card.id))
+  const unknown = cards.filter((id) => !known.has(id))
+  if (unknown.length) {
+    console.error(`paneltir: ${file} has no card called ${unknown.join(', ')}.`)
+    process.exit(1)
+  }
+
+  const by = flags.find((f) => f.startsWith('--by='))?.slice(5) === 'you' ? 'you' : 'claude'
+  const date = new Date().toISOString().slice(0, 10)
+  board.runs = Array.isArray(board.runs) ? board.runs : []
+  board.runs.unshift({
+    id: `run-${date}-${String(board.runs.length + 1).padStart(3, '0')}`,
+    date,
+    by,
+    summary,
+    cards,
+    fingerprint: shortHash,
+  })
+
+  writeFileSync(path, JSON.stringify(board, null, 2) + '\n')
+  console.log(`Appended to ${file}: ${summary}`)
+  console.log(`  ${cards.length ? `cards ${cards.join(', ')}` : 'no cards named'} · by ${by} · ${shortHash}`)
+  console.log('\nThe file is changed and not committed. The panel commits it on Save,')
+  console.log('or commit it yourself — this writes nothing to your repository.')
+}
+
+/**
+ * The board reader, loaded only by the commands that read a board.
+ *
+ * It used to be imported at module scope, which meant every command pulled in
+ * `dist/index.js` — and that bundle imports React, because it is a component
+ * library. So `paneltir init`, whose entire job is to copy seven files, and
+ * `paneltir doctor`, whose job is to hash them, both failed outright in a
+ * project that had not installed React yet. Which is exactly when somebody runs
+ * `init`.
+ *
+ * It is the same rule as the gate's, one layer up: a thing whose job is files
+ * does not carry a component library to do it. Here the fix is smaller than
+ * duplicating anything — the import just moves to where it is used.
+ */
+let readBoard
+async function boardReader() {
+  if (!readBoard) {
+    ;({ readBoard } = await import(pathToFileURL(join(here, '../dist/index.js')).href))
+  }
+  return readBoard
+}
 
 const [command, ...rest] = process.argv.slice(2)
 
@@ -343,7 +611,13 @@ switch (command) {
     check(rest)
     break
   case 'board':
-    board(rest)
+    await board(rest)
+    break
+  case 'doctor':
+    doctor()
+    break
+  case 'run':
+    await run(rest)
     break
   default:
     console.log(`paneltir v${pkg.version} · ${shortHash}
@@ -352,6 +626,8 @@ switch (command) {
   paneltir version          what is installed, and where it came from
   paneltir check [version]  fail if the installed version is not the one meant
   paneltir board [file]     read this project's board and say what is wrong
+  paneltir doctor           is the gate you copied still the gate we ship?
+  paneltir run "summary"    append what this pass did to the board's runs
 
 The components install as a library and are never edited. The gate — password,
 session, write-back — is copied in by init and belongs to the project.`)

package/dist/index.d.ts

@@ -15,6 +15,17 @@ declare const PANELTIR_VERSION: string;
 declare const PANELTIR_FINGERPRINT: string;
 /** How many files that fingerprint covers. */
 declare const PANELTIR_FILE_COUNT: number;
+/**
+ * SHA-256 over `template/` alone — the gate, the seed board and the skill file.
+ *
+ * Separate from the fingerprint above because it answers a different question.
+ * The fingerprint says which build this is; this says whether the files a
+ * project *copied out of* the package are the ones it ships now. Most releases
+ * do not touch `template/`, so those two move at different rates, and a gate
+ * checked against the version number would be reported stale on every release
+ * and believed on none.
+ */
+declare const PANELTIR_TEMPLATE_HASH: string;
 /**
  * Everything needed to report the kit in a panel's own footer or settings
  * sheet, and to check it against the released version without opening
@@ -24,6 +35,8 @@ declare const paneltirBuild: {
     readonly version: string;
     readonly fingerprint: string;
     readonly fileCount: number;
+    /** What `init` stamps, and what a gate is compared against. */
+    readonly templateHash: string;
     /** The tag this build came from, ready to compare or to link. */
     readonly tag: `v${string}`;
     /** Short form, for a footer that has one line to spare. */
@@ -1361,6 +1374,9 @@ interface UiStrings {
     needTokenEnables: string;
     needRepo: string;
     needRepoEnables: string;
+    needGate: string;
+    needGateEnables: string;
+    fixGate: string;
     fixTokenCreate: string;
     fixTokenScope: string;
     fixTokenPaste: string;
@@ -1591,6 +1607,21 @@ interface PanelAppProps {
      * collides with a preset replaces it, because the caller named it.
      */
     extraThemes?: PanelThemes;
+    /**
+     * `.paneltir/gate.json` from this project, if the caller imports it.
+     *
+     * The gate is copied once and then belongs to the project, which means it is
+     * the one part of this package that can never be told it is old — and that
+     * has cost two releases already. Handing the stamp in lets the panel say so,
+     * with no filesystem and no network, because both halves of the comparison
+     * are already data: the stamp from the project and `templateHash` from the
+     * installed package.
+     *
+     * Omitted, the panel says nothing about the gate rather than guessing. This
+     * is a prop and not a fetch for the reason the Tools screen is a prop in the
+     * demo: the kit does not decide what a caller's server can be asked.
+     */
+    gate?: unknown;
     /** Which one to draw before the board has said. Defaults to the first. */
     defaultTheme?: string;
     /**
@@ -1657,7 +1688,94 @@ interface PanelAppProps {
         fileCount: number;
     };
 }
-declare function PanelApp({ state: initialState, themes: exactThemes, extraThemes, defaultTheme, brand, decoration, className, footer, links, capabilities, extras, showLanguage, showHistory, checkForUpdates, saveEndpoint, marketplaceEndpoint, marketplaceReport, fingerprint, }: PanelAppProps): React.JSX.Element;
+declare function PanelApp({ state: initialState, themes: exactThemes, extraThemes, gate, defaultTheme, brand, decoration, className, footer, links, capabilities, extras, showLanguage, showHistory, checkForUpdates, saveEndpoint, marketplaceEndpoint, marketplaceReport, fingerprint, }: PanelAppProps): React.JSX.Element;
+
+/**
+ * Whether the gate a project is running is the gate this version ships.
+ *
+ * `template/` is the one thing here that leaves as *files a project keeps*.
+ * The components arrive in `node_modules` and are replaced on every update;
+ * the gate is copied once by `init` and is then that project's own — which is
+ * the point, since it holds their password rule and points at their
+ * repository, and a front door that moves when a library updates is not a
+ * front door.
+ *
+ * The cost of that is a copy that can never be told it is old. It has already
+ * been paid twice. The `HTTP 500` fix landed in `template/api/panel-state.ts`,
+ * so every project installed before it still has a save that cannot work, and
+ * nothing anywhere says so; `.claude/skills/panel/SKILL.md` is copied the same
+ * way, so a rule learned upstream never reaches the Claude that reads it.
+ * Upstream the copy is held honest by `test:auth` and `test:board`. Downstream
+ * there was nothing at all.
+ *
+ * So `init` records what it copied and what it copied it from, and this says
+ * what that record means. Two rules shape it:
+ *
+ * - **It compares hashes, not version numbers.** Most releases do not touch
+ *   `template/`, so "you are on 0.6.0 and 0.9.0 exists" would cry wolf for
+ *   every release and be ignored by the one that mattered. `templateHash`
+ *   ships inside `fingerprint.json`, so the comparison is exact.
+ * - **It needs no filesystem and no network**, because the panel runs in a
+ *   browser and has neither. Everything it judges is data the caller already
+ *   holds: the stamp from the project, the hash from the installed package.
+ *
+ * It reports and never repairs. Replacing somebody's gate is `init --force`,
+ * typed by a person who has read what changed.
+ */
+/**
+ * What `init` wrote, and what it wrote it from.
+ *
+ * Lives at `.paneltir/gate.json` in the project. It is not a lockfile and
+ * nothing resolves against it — it exists so a later session can tell "you
+ * edited this" from "we changed this underneath you", which is the distinction
+ * a bare diff cannot make.
+ */
+interface GateStamp {
+    /** The kit version that copied these files. */
+    version: string;
+    /** `templateHash` from that version's `fingerprint.json`. */
+    templateHash: string;
+    /** When, so a reader can date it against their own git history. */
+    copiedAt: string;
+    /**
+     * SHA-256 of each file as written, keyed by its path in the project.
+     *
+     * This is what separates a file the project edited from one the template
+     * moved under. Absent for a file `init` left alone: we did not write it, so
+     * we cannot claim to know where it came from.
+     */
+    files: Record<string, string>;
+}
+type GateVerdict = 
+/** The gate is the one this version ships. */
+'current'
+/** `template/` has changed since this gate was copied. */
+ | 'behind'
+/**
+ * No stamp. Every project installed before stamping existed is here, and it
+ * is not a fault — it is the absence of an answer, which is why it is not
+ * called one. `paneltir doctor` can still compare the files themselves.
+ */
+ | 'unstamped';
+interface GateReading {
+    verdict: GateVerdict;
+    /** The version that copied the gate, when a stamp says so. */
+    copiedFrom?: string;
+    /** The version running now. */
+    installed: string;
+}
+/**
+ * Reads a stamp against the installed package.
+ *
+ * Deliberately total: a malformed or absent stamp answers `unstamped` rather
+ * than throwing. This is called while a panel is drawing, and a panel that
+ * fails to open because it could not classify its own gate would be a worse
+ * outcome than the drift it was looking for.
+ */
+declare function gateStatus(stamp: unknown, installed: {
+    version: string;
+    templateHash?: string;
+}): GateReading;
 
 /**
  * Applies a board move to the flat card list.
@@ -1717,4 +1835,4 @@ interface CardSheetProps {
 }
 declare function CardSheet({ card, state, lang, ui, onChange, onDelete, onClose }: CardSheetProps): React.JSX.Element | null;
 
-export { ANALYSIS_SECTIONS, AlertBanner, type AlertBannerProps, type Analysis, type AnalysisSection, AnalysisView, BOARD_VERSION, Board, type BoardCardData, type BoardCheck, type BoardColumnData, type BoardFacts, type BoardMoveResult, type BoardProblem, type BoardProps, type BoardTag, CAPABILITIES, type Capability, Card$1 as Card, type CardProps, CardSheet, type Check, type Choice, type ChoiceOption, type ColumnDef, type Competitor, type Constraint, CopyBlock, type CopyBlockLabels, type CopyBlockProps, type Counts, DashboardHeader, type DashboardHeaderProps, type DashboardThemeForm, DashboardThemeProvider, type DashboardThemeTokens, DetailSection, type DetailSectionProps, DetailSheet, type DetailSheetProps, FilterChip, type FilterChipProps, FilterChipRow, type Goal, GuideNote, type GuideNoteProps, GuideTour, type GuideTourProps, type HealthFact, HealthPill, type HealthPillProps, HealthPillRow, type HealthStatus, INTENTS, INTENT_COPY, type ImportedTheme, type InstallState, type Intent, type IntentCopy, LANGS, LANG_LABELS, LEVELS, type Lang, type Level, MARKETPLACE_NAME, MARKETPLACE_URL, type Market, type MarketplaceReport, type MarketplaceTool, MarketplaceView, type Metric, type Note, NotificationBell, type NotificationBellProps, type NotificationLabels, type NotificationTone, OWNERS, type Owner, PANELTIR_FILE_COUNT, PANELTIR_FINGERPRINT, PANELTIR_VERSION, PRESET_PANEL_THEMES, PanelApp, type PanelAppProps, type Card as PanelCard, type PanelNotification, type PanelState, type PanelTheme, type PanelThemes, type Preferences, type Reading, type Run, SetupGuide, type SetupGuideProps, type SetupRequirement, type SetupStatus, SetupWizard, type SetupWizardLabels, type SetupWizardProps, type Severity, StatTile, StatTileGrid, type StatTileProps, type Strategy, type Suggestion, type SuggestionStatus, THEME_FORMS, THEME_PRESETS, type Text, type ThemeFormName, type ThemePresetName, type Trend, UI, type UiStrings, type Weight, type WizardStep, applyMove, boardFacts, checkProgress, claimedWithoutStarting, claudeTheme, commandSnippet, countCards, cyberpunkTheme, decided, emptyCard, explainBoard, isCard, isFirstRun, ledgerForm, midnightTheme, moveCardInColumns, newId, offeredThemes, oldMoneyTheme, panelForm, paneltirBuild, paperForm, readBoard, readStoredLang, repositorySnippet, resetGuide, sparkPoints, stampForColumn, storeLang, text, today, trendOf, undecided, untranslated, useDashboardForm, useDashboardTheme, useDelegatedClick, useGuideNote, useMediaQuery, validateBoard, wizardStep, writeText };
+export { ANALYSIS_SECTIONS, AlertBanner, type AlertBannerProps, type Analysis, type AnalysisSection, AnalysisView, BOARD_VERSION, Board, type BoardCardData, type BoardCheck, type BoardColumnData, type BoardFacts, type BoardMoveResult, type BoardProblem, type BoardProps, type BoardTag, CAPABILITIES, type Capability, Card$1 as Card, type CardProps, CardSheet, type Check, type Choice, type ChoiceOption, type ColumnDef, type Competitor, type Constraint, CopyBlock, type CopyBlockLabels, type CopyBlockProps, type Counts, DashboardHeader, type DashboardHeaderProps, type DashboardThemeForm, DashboardThemeProvider, type DashboardThemeTokens, DetailSection, type DetailSectionProps, DetailSheet, type DetailSheetProps, FilterChip, type FilterChipProps, FilterChipRow, type GateReading, type GateStamp, type GateVerdict, type Goal, GuideNote, type GuideNoteProps, GuideTour, type GuideTourProps, type HealthFact, HealthPill, type HealthPillProps, HealthPillRow, type HealthStatus, INTENTS, INTENT_COPY, type ImportedTheme, type InstallState, type Intent, type IntentCopy, LANGS, LANG_LABELS, LEVELS, type Lang, type Level, MARKETPLACE_NAME, MARKETPLACE_URL, type Market, type MarketplaceReport, type MarketplaceTool, MarketplaceView, type Metric, type Note, NotificationBell, type NotificationBellProps, type NotificationLabels, type NotificationTone, OWNERS, type Owner, PANELTIR_FILE_COUNT, PANELTIR_FINGERPRINT, PANELTIR_TEMPLATE_HASH, PANELTIR_VERSION, PRESET_PANEL_THEMES, PanelApp, type PanelAppProps, type Card as PanelCard, type PanelNotification, type PanelState, type PanelTheme, type PanelThemes, type Preferences, type Reading, type Run, SetupGuide, type SetupGuideProps, type SetupRequirement, type SetupStatus, SetupWizard, type SetupWizardLabels, type SetupWizardProps, type Severity, StatTile, StatTileGrid, type StatTileProps, type Strategy, type Suggestion, type SuggestionStatus, THEME_FORMS, THEME_PRESETS, type Text, type ThemeFormName, type ThemePresetName, type Trend, UI, type UiStrings, type Weight, type WizardStep, applyMove, boardFacts, checkProgress, claimedWithoutStarting, claudeTheme, commandSnippet, countCards, cyberpunkTheme, decided, emptyCard, explainBoard, gateStatus, isCard, isFirstRun, ledgerForm, midnightTheme, moveCardInColumns, newId, offeredThemes, oldMoneyTheme, panelForm, paneltirBuild, paperForm, readBoard, readStoredLang, repositorySnippet, resetGuide, sparkPoints, stampForColumn, storeLang, text, today, trendOf, undecided, untranslated, useDashboardForm, useDashboardTheme, useDelegatedClick, useGuideNote, useMediaQuery, validateBoard, wizardStep, writeText };

package/dist/index.js

@@ -1,11 +1,14 @@
 // src/version.ts
-var PANELTIR_VERSION = "0.9.0";
-var PANELTIR_FINGERPRINT = "sha256:f65d491a7350ddce22f6981dbcb91531f5e88fc66b7f9f8f83115d802773064f";
-var PANELTIR_FILE_COUNT = 161;
+var PANELTIR_VERSION = "0.10.0";
+var PANELTIR_FINGERPRINT = "sha256:4de7ef7076563e4c3118ac16b645737a44c4c0675115d9a9d7bbff562d5ecb74";
+var PANELTIR_FILE_COUNT = 163;
+var PANELTIR_TEMPLATE_HASH = "sha256:7f9accd11920a0c189dd683bdb96635a606960afeca71e02c2a26a0257acefd8";
 var paneltirBuild = {
   version: PANELTIR_VERSION,
   fingerprint: PANELTIR_FINGERPRINT,
   fileCount: PANELTIR_FILE_COUNT,
+  /** What `init` stamps, and what a gate is compared against. */
+  templateHash: PANELTIR_TEMPLATE_HASH,
   /** The tag this build came from, ready to compare or to link. */
   tag: `v${PANELTIR_VERSION}`,
   /** Short form, for a footer that has one line to spare. */
@@ -1472,6 +1475,18 @@ function offeredThemes(themes, extraThemes) {
   return offered;
 }
 
+// src/gate/stamp.ts
+function gateStatus(stamp, installed) {
+  const reading = { verdict: "unstamped", installed: installed.version };
+  if (typeof stamp !== "object" || stamp === null) return reading;
+  const candidate = stamp;
+  if (typeof candidate.templateHash !== "string" || candidate.templateHash === "") return reading;
+  if (typeof candidate.version === "string" && candidate.version) reading.copiedFrom = candidate.version;
+  if (typeof installed.templateHash !== "string" || installed.templateHash === "") return reading;
+  reading.verdict = candidate.templateHash === installed.templateHash ? "current" : "behind";
+  return reading;
+}
+
 // src/panel/AnalysisView.tsx
 import { useMemo as useMemo3, useState as useState7 } from "react";
 
@@ -1599,6 +1614,9 @@ var UI = {
     needTokenEnables: "Lets Save commit the board back to the repository. Without it everything else works and Save fails.",
     needRepo: "The repository to write to",
     needRepoEnables: "Which repository the board is committed to. There is no default on purpose: writing to the wrong one is worse than not writing.",
+    needGate: "The gate this project copied",
+    needGateEnables: "The sign-in, the session and the write-back are files this project owns, copied once and never updated with the library. When one of them is older than the package, the panel does not look misconfigured \u2014 it looks broken.",
+    fixGate: "The gate is older than the installed kit. See what changed before replacing anything:",
     fixTokenCreate: "On GitHub, make a fine-grained personal access token.",
     fixTokenScope: "Give it Contents: read and write, on this repository only \u2014 nothing else, and no other repository.",
     fixTokenPaste: "Paste it into the hosting project as GH_TOKEN. Never into the repository: a token in a commit is a token to revoke.",
@@ -1920,6 +1938,9 @@ var UI = {
     needTokenEnables: "Permite que Guardar confirme el tablero en el repositorio. Sin \xE9l todo lo dem\xE1s funciona y Guardar falla.",
     needRepo: "El repositorio donde escribir",
     needRepoEnables: "En qu\xE9 repositorio se confirma el tablero. No hay valor por defecto a prop\xF3sito: escribir en el equivocado es peor que no escribir.",
+    needGate: "La puerta que copi\xF3 este proyecto",
+    needGateEnables: "El acceso, la sesi\xF3n y la escritura de vuelta son archivos de este proyecto, copiados una vez y que no se actualizan con la librer\xEDa. Cuando uno se queda m\xE1s viejo que el paquete, el panel no parece mal configurado: parece roto.",
+    fixGate: "La puerta es m\xE1s vieja que el kit instalado. Mira qu\xE9 cambi\xF3 antes de reemplazar nada:",
     fixTokenCreate: "En GitHub, crea un token de acceso personal de tipo fine-grained.",
     fixTokenScope: "Dale Contents: read and write, solo sobre este repositorio \u2014 nada m\xE1s, y ning\xFAn otro repositorio.",
     fixTokenPaste: "P\xE9galo en el proyecto de hosting como GH_TOKEN. Nunca en el repositorio: un token en un commit es un token que hay que revocar.",
@@ -2977,6 +2998,7 @@ function PanelApp({
   state: initialState,
   themes: exactThemes,
   extraThemes,
+  gate,
   defaultTheme,
   brand,
   decoration,
@@ -2994,6 +3016,7 @@ function PanelApp({
   fingerprint
 }) {
   const themes = useMemo5(() => offeredThemes(exactThemes, extraThemes), [exactThemes, extraThemes]);
+  const gateReading = useMemo5(() => gateStatus(gate, paneltirBuild), [gate]);
   const [themeName, setThemeName] = useState10(
     () => resolveTheme(
       initialState.preferences?.theme,
@@ -3065,9 +3088,39 @@ function PanelApp({
         variable: "PANEL_REPO",
         enables: ui.needRepoEnables,
         fix: /* @__PURE__ */ jsx20("p", { children: ui.fixRepo })
-      }
+      },
+      // The gate is the only requirement here that is not an environment
+      // variable: it is files this project owns, and the only one whose
+      // failure is silent. A stale `api/panel-state.ts` does not read as
+      // missing configuration — it reads as the panel being broken, which is
+      // how the HTTP 500 cost a week.
+      //
+      // Drawn only when a stamp was passed. The kit does not invent a
+      // requirement out of the absence of a prop: this project's own panel has
+      // no copied gate — `template/` is the original, held honest by
+      // `test:auth` — so a row here would invite wiring something that cannot
+      // exist. A caller who passes nothing still has `paneltir doctor`, which
+      // is what the skill file sends their Claude to.
+      //
+      // Passed but unreadable is a different thing and *is* reported, as
+      // `unknown` rather than `missing`: telling somebody their gate is old on
+      // the strength of a file we failed to parse is the mistake
+      // `SetupWizard` already refuses to make.
+      ...gate === void 0 ? [] : [{
+        id: "gate",
+        label: ui.needGate,
+        status: gateReading.verdict === "current" ? "ok" : gateReading.verdict === "behind" ? "missing" : "unknown",
+        enables: ui.needGateEnables,
+        fix: /* @__PURE__ */ jsxs18(Fragment5, { children: [
+          /* @__PURE__ */ jsxs18("p", { children: [
+            ui.fixGate,
+            gateReading.copiedFrom ? ` (v${gateReading.copiedFrom} \u2192 v${gateReading.installed})` : ""
+          ] }),
+          /* @__PURE__ */ jsx20("pre", { className: "pt-copy__pre", children: "npx paneltir doctor" })
+        ] })
+      }]
     ];
-  }, [setup, ui]);
+  }, [setup, ui, gate, gateReading]);
   useEffect9(() => {
     document.documentElement.lang = lang;
     if (showLanguage) storeLang(lang);
@@ -4236,6 +4289,7 @@ export {
   OWNERS,
   PANELTIR_FILE_COUNT,
   PANELTIR_FINGERPRINT,
+  PANELTIR_TEMPLATE_HASH,
   PANELTIR_VERSION,
   PRESET_PANEL_THEMES,
   PanelApp,
@@ -4257,6 +4311,7 @@ export {
   decided,
   emptyCard,
   explainBoard,
+  gateStatus,
   isCard,
   isFirstRun,
   ledgerForm,

package/fingerprint.json

@@ -1,7 +1,8 @@
 {
   "name": "paneltir",
-  "version": "0.9.0",
-  "hash": "sha256:f65d491a7350ddce22f6981dbcb91531f5e88fc66b7f9f8f83115d802773064f",
-  "fileCount": 161,
-  "generatedAt": "2026-09-10T03:50:24.162Z"
+  "version": "0.10.0",
+  "hash": "sha256:4de7ef7076563e4c3118ac16b645737a44c4c0675115d9a9d7bbff562d5ecb74",
+  "fileCount": 163,
+  "templateHash": "sha256:7f9accd11920a0c189dd683bdb96635a606960afeca71e02c2a26a0257acefd8",
+  "generatedAt": "2026-09-11T02:49:51.562Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paneltir",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A React UI kit for admin panels: page frame, a board with touch-ready drag and drop, detail sheets, and a whole panel in one component. Structure and behaviour are fixed; colour and brand belong to each project.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "DFKlabs (https://DFKlabs.com)",
@@ -64,7 +64,7 @@
     "check:boards": "node scripts/check-boards.mjs",
     "demo:install": "npm --prefix examples/demo ci",
     "demo:build": "npm --prefix examples/demo run build",
-    "verify": "npm run typecheck && npm run build && npm run icons:check && npm run seo:check && npm run test:auth && npm run test:marketplace && npm run test:init && npm run test:board && npm run test:move && npm run test:theme && npm run test:setup && npm run test:updates && npm run release-notes:check && npm run check:boards && npm run check:docs && npm run check:package && npm run fingerprint:check",
+    "verify": "npm run typecheck && npm run build && npm run icons:check && npm run seo:check && npm run test:auth && npm run test:marketplace && npm run test:init && npm run test:board && npm run test:gate && npm run test:move && npm run test:theme && npm run test:setup && npm run test:updates && npm run release-notes:check && npm run check:boards && npm run check:docs && npm run check:package && npm run fingerprint:check",
     "site:install": "npm --prefix site ci",
     "site:dev": "npm --prefix site run dev",
     "site:build": "npm --prefix site run build",
@@ -78,7 +78,8 @@
     "test:board": "node scripts/test-board.mjs",
     "test:move": "node scripts/test-move.mjs",
     "test:theme": "node scripts/test-theme.mjs",
-    "test:setup": "node scripts/test-setup.mjs"
+    "test:setup": "node scripts/test-setup.mjs",
+    "test:gate": "node scripts/test-gate.mjs"
   },
   "peerDependencies": {
     "react": ">=18",
@@ -98,35 +99,42 @@
     "node": ">=20"
   },
   "paneltirRelease": {
-    "version": "0.9.0",
-    "date": "2026-09-10",
+    "version": "0.10.0",
+    "date": "2026-09-11",
     "entries": [
       {
         "kind": "feature",
         "text": {
-          "en": "A project's own theme can be offered alongside the kit's four instead of replacing them. Pass it as `extraThemes`; `themes` still means \"exactly these\".",
-          "es": "El tema propio de un proyecto puede ofrecerse junto a los cuatro del kit en vez de sustituirlos. Pásalo como `extraThemes`; `themes` sigue significando «exactamente estos»."
+          "en": "`paneltir doctor` says whether the files this project copied are still the ones the installed kit ships — and separates \"you edited it\" from \"we changed it underneath you\", which a diff cannot.",
+          "es": "`paneltir doctor` dice si los archivos que copió este proyecto siguen siendo los del kit instalado — y separa «lo editaste tú» de «lo cambiamos nosotros debajo», que un diff no puede."
         }
       },
       {
-        "kind": "fix",
+        "kind": "feature",
+        "text": {
+          "en": "The setup list can carry a row for the copied gate. Import `.paneltir/gate.json` and pass it as `gate`; without it the panel says nothing about those files rather than guessing.",
+          "es": "La lista de configuración puede llevar una fila para la puerta copiada. Importa `.paneltir/gate.json` y pásalo como `gate`; sin él el panel no dice nada de esos archivos en vez de suponer."
+        }
+      },
+      {
+        "kind": "feature",
         "text": {
-          "en": "A panel that passed one theme of its own showed a settings sheet with a single row: the four presets were silently gone. They are back, and the project's own identity is what the panel opens in.",
-          "es": "Un panel que pasaba un tema propio mostraba un solo tema en los ajustes: los cuatro presets desaparecían sin decir nada. Han vuelto, y el panel abre con la identidad del proyecto."
+          "en": "`paneltir run \"what this pass did\"` appends to the board's revisions, so the record does not depend on anyone remembering at the end of a session.",
+          "es": "`paneltir run \"qué hizo esta pasada\"` añade una entrada a las revisiones del tablero, así el registro no depende de que alguien se acuerde al final de la sesión."
         }
       },
       {
         "kind": "fix",
         "text": {
-          "en": "A theme derived from a project is drawn in the kit's own default shape rather than borrowing the shape of an unrelated theme.",
-          "es": "Un tema derivado de un proyecto se dibuja con la forma por defecto del kit, en vez de tomar prestada la de un tema que no tiene nada que ver."
+          "en": "`paneltir init` and `paneltir doctor` no longer need React installed. They loaded the component bundle at startup, so they failed in a project that had not installed it yet — which is exactly when `init` is run.",
+          "es": "`paneltir init` y `paneltir doctor` ya no necesitan React instalado. Cargaban el bundle de componentes al arrancar, así que fallaban en un proyecto que aún no lo tenía — que es justo cuando se ejecuta `init`."
         }
       },
       {
         "kind": "chore",
         "text": {
-          "en": "The install instructions name every theme the kit ships. They named three of four, so the only light one was never offered to a project — and a check now refuses to let that happen again.",
-          "es": "Las instrucciones de instalación nombran todos los temas que trae el kit. Nombraban tres de cuatro, así que el único claro no se ofrecía nunca — y ahora una comprobación impide que vuelva a pasar."
+          "en": "The rules a project needs are checked to actually reach it: the documents a project keeps must name `extraThemes` and `paneltir doctor`, or the build fails saying why.",
+          "es": "Se comprueba que las reglas que un proyecto necesita le lleguen de verdad: los documentos que el proyecto conserva tienen que nombrar `extraThemes` y `paneltir doctor`, o la build falla diciendo por qué."
         }
       }
     ]

package/template/.claude/skills/panel/SKILL.md

@@ -132,6 +132,35 @@ Never invent a palette. If the project has no colours of its own, say so and
 leave the theme alone — the kit ships presets for exactly that case, and one
 of them is a light theme.
 
+And when you hand this project's own theme to `PanelApp`, it goes in
+**`extraThemes`** and never in `themes`. `extraThemes` offers it as well as the
+kit's four; `themes` means "exactly these", so one theme passed there deletes
+every preset and the settings sheet shows a single row. Two projects were
+installed that way before the distinction existed, and the symptom reads as the
+kit having no themes rather than as a prop being wrong.
+
+## When the panel behaves oddly for no visible reason
+
+The gate — `middleware.ts`, `lib/session.ts`, `api/*.ts` — was copied into this
+project once and does **not** update when the kit does. So a fix released
+upstream can be missing here while every version number on the screen looks
+current, and nothing says so: the `HTTP 500` on saving lived in
+`api/panel-state.ts` and stayed in projects installed before the fix.
+
+    npx paneltir doctor
+
+`.paneltir/gate.json` is what makes that answer sharp, and it belongs in git:
+it records what `init` copied and from where. Ignored, it vanishes on the next
+clone and every file degrades to "differs" — the one answer that cannot say
+whether you moved it or we did.
+
+It separates the three answers that need different actions: *yours* (you edited
+it), *BEHIND* (you did not touch it and the template moved), and *BOTH*. The
+middle one is invisible to `git diff`, because there is nothing in this
+project's history to compare against. `paneltir init --force` replaces the gate
+and never the board — read the diff first when a file is marked BOTH, or the
+edit is lost.
+
 ## Setting the panel up in the first place
 
 The panel is asked for this by name: its walkthrough carries a line the owner