paneltir 0.6.0

package/CLAUDE_MD_SNIPPET.md

@@ -0,0 +1,66 @@
+# Block to paste into each consumer project's CLAUDE.md (not this repository's)
+
+This is not documentation of the kit — it is the block that goes into the
+`CLAUDE.md` of every project that uses it. `CLAUDE.md` is reloaded every
+session, unlike `INSTALL.md`, which is read once at install time. This is the
+rule that has to survive a "just add X to the dashboard" request six months
+from now, without anyone repeating it.
+
+---
+
+## Admin dashboard
+
+This project's admin dashboard uses `paneltir` (`node_modules/paneltir`), a
+library shared with other projects. Rules:
+
+- **Never edit files inside `node_modules/paneltir`.** Not even when asked to
+  "change the dashboard" or "add X to the cards" — that phrasing almost always
+  means the content or the data, not the library.
+- **Content, data and business logic** (which columns exist, what each card
+  shows, where the data comes from, what happens on click) live in
+  `src/dashboard/` <!-- adjust to this project's real path --> and are built
+  by composing the kit's components (`Board`, `Card`, `StatTile`, and so on —
+  props like `children` and `renderCard` exist for this).
+- **If a request implies changing the structure or behaviour of the kit
+  itself** (layout, how drag and drop works, theming), do not solve it
+  locally: say so explicitly before touching anything. That change belongs in
+  the `paneltir` repository and reaches this project as a new version. See
+  `node_modules/paneltir/INSTALL.md` for the order to follow (composition →
+  change in the kit → patch-package).
+- The dashboard palette lives in <!-- path to this project's theme file, e.g.
+  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.
+- **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
+  rule and point at this project's repository. Edit them here; they do not
+  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.
+- **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,
+  per browser. **Help** in the header reports what the panel needs — the
+  password, the GitHub token, the target repository — with what is missing and
+  the steps to fix it, asked from the server so it reports the truth rather
+  than a guess. "Show the guide again" in there brings the tour back.
+- **Say which version the dashboard runs on.** `paneltirBuild.short` from
+  `paneltir` renders as `vX.Y.Z · <first 12 of the fingerprint>`; keep it visible somewhere in
+  the panel. `npx paneltir version` answers the same question from a terminal,
+  and `npx paneltir check <version>` exits non-zero when what is installed is
+  not what was meant.
+- **The board's shape is checked, so a broken one says which line.** Editing
+  `src/data/panel-state.json` by hand is allowed, and sometimes the fastest
+  way. Run `npx paneltir board` afterwards: it names every problem — a card in
+  a column that was renamed, an intent nothing can honour, a completion with no
+  start — instead of the panel opening on a blank screen. The write API refuses
+  the same shapes, so a bad save never reaches the repository.
+- **Kit fingerprint (so re-reading it does not cost tokens).** The version of
+  `paneltir` integrated here has the hash
+  `<!-- paste the "hash" field from node_modules/paneltir/fingerprint.json -->`.
+  Before re-reading `node_modules/paneltir/README.md`, `INSTALL.md` or its
+  source, compare that value with the current `hash` in
+  `node_modules/paneltir/fingerprint.json`: **if they match, the kit did not
+  change and nothing needs to be read again.** If they differ, read only what
+  is necessary — the `files` map names which files changed — and update this
+  hash afterwards.

package/INSTALL.md

@@ -0,0 +1,261 @@
+# Install instructions (written for Claude Code)
+
+> This file is an instruction for an agent, not documentation for a human
+> reader. When `paneltir` should go into a project, paste this — or "follow
+> the instructions in paneltir's INSTALL.md" — to Claude Code in that
+> repository. Nothing else needs explaining.
+
+## Task
+
+Install `paneltir` in this project so that the admin dashboard uses the
+kit's structure and behaviour, but **with this project's own visual
+identity** — never another project's.
+
+## Steps
+
+1. **Install the package**, pinned to an exact tag:
+
+   ```bash
+   npm install paneltir
+
+   # or, without npm access, straight from the repository:
+   # npm install github:daifukus/paneltir#v0.6.0
+   ```
+
+   (Use the tag you were given; never install without pinning a version.)
+
+2. **Find the palette this project already has**, before writing anything.
+   `npx paneltir init` names the files it found it in, if the gate is being
+   installed too.
+   Look, in this order:
+   - an existing design-token or theme file (`theme.ts`, `colors.ts`,
+     `tailwind.config.js`, CSS variables in `globals.css` or similar);
+   - the colours already used by current components (buttons, header,
+     backgrounds);
+   - the project's branding (name, logo, any brand guide in the repository).
+
+   **Do not invent a new palette when one already exists.** The goal is a
+   dashboard that looks like part of *this* project, not a generic theme and
+   not another project's theme.
+
+3. **If no palette is defined yet**, do not make up values: `paneltir` ships
+   base themes that are already designed and tested (`cyberpunkTheme`,
+   `midnightTheme`, `oldMoneyTheme`, all exported in `THEME_PRESETS`). Ask
+   which one fits the project best — and if the answer is not available right
+   now, use `midnightTheme`, the most neutral one, and say so explicitly.
+   Store the decision in a new file (for example `src/dashboard-theme.ts`),
+   re-exporting the chosen preset, or copying its values if they are expected
+   to diverge:
+
+   ```tsx
+   // src/dashboard-theme.ts
+   export { cyberpunkTheme as dashboardTheme } from 'paneltir'
+   ```
+
+   Make it clear in the code that this is a decision that was taken, and
+   which preset it came from — not a placeholder.
+
+4. **Map those colours to `DashboardThemeTokens`** (the interface the package
+   exports): `ground`, `groundRaised`, `panel`, `raised`, `line`, `lineFaint`,
+   `ink`, `inkDim`, `inkFaint`, `accent` (plus optional `accentStart`,
+   `accentEnd`, `accentInk`), `danger`, `warning`, `success`, `neutral`. Each
+   role is documented in the package's `.d.ts` — read it before guessing what
+   belongs where.
+
+5. **Optionally pick a form.** Colour alone leaves every project the same
+   object repainted. A `DashboardThemeForm` chooses the *shape* instead:
+   `shape: 'panel'` (the default — raised cards floating in a rounded column)
+   or `shape: 'ledger'` (a ruled book: no fill, hairline rows, priority marked
+   in the gutter, set in a serif). `THEME_FORMS.panel` and `THEME_FORMS.ledger`
+   are ready to use, and the other fields — radii, `borderWidth`,
+   `fontFamily`, `labelTracking`, `density` — tune whichever is chosen. Skip
+   this and the kit renders exactly as it always has.
+
+6. **Wrap this project's admin section**:
+
+   ```tsx
+   import { DashboardThemeProvider, THEME_FORMS } from 'paneltir'
+   import 'paneltir/style.css'
+
+   <DashboardThemeProvider tokens={thisProjectTokens} form={THEME_FORMS.panel}>
+     {/* dashboard */}
+   </DashboardThemeProvider>
+   ```
+
+   The `import 'paneltir/style.css'` goes in once, at the dashboard's entry
+   point — do not repeat it per screen.
+
+   To give this project its own typeface, set `--pt-font-family` (or the form's
+   `fontFamily`) — never `font-family` on the element the provider renders: the
+   form's face is written inline there, and a stylesheet rule on the same
+   element would silently win.
+
+7. **Build the screens with the kit's components** (`Board`, `Card`,
+   `StatTile`, `HealthPill`, `FilterChip`, `DetailSheet` and the rest — see
+   `paneltir`'s `README.md` for the full list and examples), wired to this
+   project's real data. Business logic, data fetching and what goes in each
+   column or card remain this project's responsibility: the kit neither
+   provides nor assumes them.
+
+8. **Install the gate, the board and the skill:**
+
+   ```bash
+   npx paneltir init
+   ```
+
+   **It looks at the project before it writes.** Most projects installing this
+   are not empty: they have a palette, an admin area, often a password already
+   in use, sometimes another dashboard package still installed. `init` reports
+   each one it finds and says what to do about it — reuse the password rather
+   than adding a second, build inside the existing admin area rather than
+   beside it, adopt the palette rather than inventing one. It reads names, never
+   values: no secret is printed.
+
+   It copies three things, and all of them belong to the project once written:
+
+   - **The gate** — `middleware.ts`, `lib/session.ts`, `api/login.ts`,
+     `api/logout.ts`, `api/panel-state.ts`. Not part of the library: they hold
+     this project's password rule, point at this project's repository, and run
+     on the hosting platform rather than in the bundle. Shipping them inside
+     the library would mean every project's front door moving whenever the
+     library updates.
+   - **The board** — `src/data/panel-state.json`, empty, with the columns
+     already there and three questions nobody has answered. It is the only
+     file `init --force` will not replace: it stops being a template the
+     moment this project writes its first card into it.
+   - **The skill** — `.claude/skills/panel/SKILL.md`, which is how *this
+     project's* Claude knows what the board means: that `order` is a request,
+     that three of the nine intents are refusals, what moving a card claims,
+     and that a standing question with no answer is asked rather than guessed.
+     Say `/panel` in a session to use it.
+
+   Re-running `init` never overwrites anything that is already there, and
+   `--force` replaces only the gate.
+
+   **Then mount the panel. It is one component, not an assembly.**
+
+   ```tsx
+   import 'paneltir/style.css'
+   import { PanelApp } from 'paneltir'
+   import board from './data/panel-state.json'
+
+   <PanelApp state={board} saveEndpoint="/admin/api/panel-state" showHistory />
+   ```
+
+   That is the whole page. `PanelApp` draws the board, the analysis, the card
+   sheet, the settings, the guide and the notifications, and it offers the
+   kit's themes with no further configuration. Everything a project wants
+   differently is a prop rather than a fork:
+
+   | Prop | What it changes |
+   | --- | --- |
+   | `themes`, `defaultTheme` | The identities the settings sheet offers. Defaults to the kit's presets. |
+   | `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. |
+   | `saveEndpoint` | The one that changes behaviour rather than appearance: with it the panel commits, without it nothing is written and the guide says so. |
+
+   The components are still exported, so a project that wants to build its own
+   screen out of `Board`, `StatTile` and the rest can. `PanelApp` is there so
+   that it does not have to.
+
+   Then set these where the project is hosted — never in the repository:
+
+   | Variable | Value |
+   | --- | --- |
+   | `ADMIN_PASSWORD` | This project's panel password. Required; without it the panel answers 503 rather than becoming public. |
+   | `GH_TOKEN` | A fine-grained token with *contents: read and write* on **this project's** repository only. |
+   | `PANEL_REPO` | This project's `owner/repo`. There is no default: writing to the wrong repository is worse than not writing. |
+   | `PANEL_FILE` | Where the board lives in it, if not `src/data/panel-state.json`. |
+   | `SESSION_SECRET` | Optional. Defaults to `ADMIN_PASSWORD`, so changing the password ends every session already issued. |
+
+   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
+   `middleware.ts` at wherever this project's build emits it — protecting the
+   page but not the bundle leaves the board readable by anyone who opens the
+   HTML.
+
+9. **Record the kit fingerprint.** The kit reports itself, so no one has to
+   read `node_modules` to find out what is installed:
+
+   ```bash
+   npx paneltir version          # version, fingerprint, where it came from
+   npx paneltir check 0.6.0      # exits non-zero if that is not what is installed
+   npx paneltir board            # read the board and say what is wrong with it
+   ```
+
+   ```tsx
+   import { paneltirBuild } from 'paneltir'
+   // paneltirBuild.short → "vX.Y.Z · <first 12 of the fingerprint>"
+   ```
+
+   Put `paneltirBuild.short` somewhere the panel shows it — a footer or a
+   settings sheet. A dashboard that cannot say which version it is built on is
+   a dashboard nobody can support: "it looks wrong" and "it is three versions
+   behind" are indistinguishable from the outside. Paste the same hash into the
+   block from `CLAUDE_MD_SNIPPET.md`; comparing it later is enough to know
+   whether the kit changed, with no need to re-read its code.
+
+10. **Never edit files inside `node_modules/paneltir` by hand.** An
+    `npm install` overwrites them without warning, and the project is left with
+    an invisible divergence: `package.json` still names the same version while
+    the real code is something else. The files `paneltir init` copied are the
+    exception, and the only one: they live in the project, not in
+    `node_modules`, and are meant to be edited.
+
+## If the kit is missing something this project needs
+
+Work through this order, without skipping steps:
+
+1. **Can it be solved by composition, without touching the kit?** Most cases
+   land here. `Card` takes `children` for extra content, `Board` takes
+   `renderCard` for full control over how each card looks, and
+   `DetailSheet`/`DetailSection` are generic containers. Build the new
+   behaviour in this project's code, wrapping the kit's components rather than
+   modifying them.
+
+2. **Is it structural, and will the other projects need it eventually** (a new
+   component, a change to how dragging behaves, a layout adjustment)? Then the
+   change belongs in the `paneltir` repository: make it there, test it, tag a
+   new version, and update this project to that version. Do not simulate it
+   locally "in the meantime".
+
+3. **Is it genuinely specific to this project**, with no reason to live in the
+   shared kit? Then diverging is fine, but do it traceably:
+
+   ```bash
+   npx patch-package paneltir
+   ```
+
+   after editing the code inside `node_modules/paneltir`. That generates
+   `patches/paneltir+<version>.patch`, which is committed to the repository
+   and re-applied on every `npm install` (this needs a `postinstall:
+   patch-package` script in this project's `package.json` — add it if it is
+   missing). Unlike a hand edit, the patch is versioned and tied to an exact
+   version of the kit: if the project moves to a newer kit and the patch no
+   longer applies, it fails loudly instead of disappearing in silence, and
+   that is the signal to decide whether the patch is still needed.
+
+   Leave a comment above the patch, or in the commit, explaining why it
+   exists, so it is a documented decision rather than a mystery six months
+   from now.
+
+Divergence between projects is not the problem — it happens with any shared
+library. The problem is invisible divergence. With versions pinned by tag plus
+`patch-package` for what is truly specific, reading a project's `package.json`
+and `patches/` folder is enough to know exactly which version it is on and
+what was added on top.
+
+## How to check it went well
+
+- The dashboard shows *this* project's colours and brand, not generic colours
+  and not another project's.
+- No file in this repository hard-codes a colour for a kit component —
+  everything goes through the tokens from step 4.
+- The board's drag and drop works on touch (try a narrow viewport or touch
+  emulation), not just with a mouse.
+- There are no hand edits inside `node_modules/paneltir`: anything the kit was
+  missing is either composed in this project's own code or recorded as a
+  `patch-package` patch in `patches/`.
+- This project's `CLAUDE.md` carries the kit fingerprint from step 7.

package/LICENSE

@@ -0,0 +1,90 @@
+LICENCIA PROPIETARIA DE PANELTIR
+Versión 1.0 — 4 de septiembre de 2026
+
+Copyright (c) 2026 DFKlabs (daifukus). Todos los derechos reservados.
+
+Este software, incluido su código fuente, código compilado, documentación,
+temas, ejemplos y cualquier material asociado (en conjunto, el "Software",
+conocido comercialmente como "Paneltir"), es propiedad exclusiva de DFKlabs
+(el "Titular") y está protegido por las leyes de propiedad intelectual y los
+tratados internacionales aplicables.
+
+1. AUSENCIA DE LICENCIA ABIERTA
+   Este NO es software libre ni de código abierto. El hecho de que el código
+   sea visible en un repositorio no otorga ningún derecho sobre él. Salvo lo
+   expresamente autorizado por escrito por el Titular, no se concede ninguna
+   licencia, expresa o implícita, sobre el Software.
+
+2. USO PERMITIDO
+   El Titular autoriza el uso del Software únicamente a:
+   a) el propio Titular y las personas que trabajen bajo su dirección;
+   b) los proyectos, productos y clientes que el Titular designe de forma
+      expresa y por escrito.
+   Cualquier otra persona o entidad que acceda al Software debe limitarse a
+   consultarlo y no adquiere derecho alguno de uso.
+
+3. PROHIBICIONES
+   Sin autorización previa, expresa y por escrito del Titular, queda prohibido:
+   a) copiar, reproducir, distribuir, publicar, sublicenciar, alquilar, vender
+      o ceder el Software, en todo o en parte;
+   b) modificar, traducir, adaptar o crear obras derivadas del Software;
+   c) incorporar el Software, o fragmentos de él, en otros productos, servicios
+      o bibliotecas, propios o de terceros;
+   d) redistribuir el Software como dependencia (npm, Git u otro mecanismo)
+      fuera de los proyectos autorizados según la cláusula 2;
+   e) eliminar, ocultar o alterar avisos de autoría, copyright o de esta
+      licencia;
+   f) utilizar el Software, su documentación o su código para entrenar,
+      ajustar o evaluar modelos de aprendizaje automático;
+   g) utilizar el nombre "Paneltir", "DFKlabs" o cualquier marca asociada para
+      promocionar productos o servicios sin consentimiento del Titular.
+
+4. TITULARIDAD
+   El Software se licencia, no se vende. El Titular conserva todos los
+   derechos, títulos e intereses sobre el Software, incluidas las
+   contribuciones que terceros aporten al repositorio. Al enviar una
+   contribución, el contribuyente cede al Titular todos los derechos sobre
+   ella de forma irrevocable y gratuita.
+
+5. CONFIDENCIALIDAD
+   El acceso al Software se concede con carácter confidencial. Quien acceda a
+   él se compromete a no revelarlo a terceros no autorizados.
+
+6. TERMINACIÓN
+   Cualquier incumplimiento de esta licencia extingue de forma automática e
+   inmediata todo permiso de uso. En ese caso, deberá cesarse en el uso del
+   Software y destruirse todas las copias en su poder.
+
+7. AUSENCIA DE GARANTÍA
+   EL SOFTWARE SE ENTREGA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O
+   IMPLÍCITA, INCLUIDAS, SIN LIMITACIÓN, LAS GARANTÍAS DE COMERCIALIZACIÓN,
+   IDONEIDAD PARA UN FIN DETERMINADO Y NO INFRACCIÓN.
+
+8. LIMITACIÓN DE RESPONSABILIDAD
+   EN NINGÚN CASO EL TITULAR SERÁ RESPONSABLE DE DAÑOS DIRECTOS, INDIRECTOS,
+   INCIDENTALES, ESPECIALES O CONSECUENTES DERIVADOS DEL USO O LA IMPOSIBILIDAD
+   DE USO DEL SOFTWARE, AUNQUE SE LE HAYA ADVERTIDO DE LA POSIBILIDAD DE TALES
+   DAÑOS.
+
+9. LEGISLACIÓN APLICABLE
+   Esta licencia se rige por la legislación del domicilio del Titular. Toda
+   controversia se someterá a los tribunales competentes de dicho domicilio.
+
+10. CONTACTO
+    Para solicitar una autorización de uso, distribución o licencia comercial,
+    contactar con el Titular a través de https://DFKlabs.com.
+
+---
+
+PANELTIR PROPRIETARY LICENSE (English summary — the Spanish text above
+prevails)
+
+Copyright (c) 2026 DFKlabs (daifukus). All rights reserved.
+
+This is NOT open-source software. Source visibility grants no rights. Use is
+restricted to the copyright holder and to projects it explicitly authorises in
+writing. Copying, redistribution, modification, sublicensing, incorporation
+into other products, and use for training machine-learning models are
+prohibited without prior written consent. Contributions are assigned to the
+holder. The software is provided "AS IS", without warranty of any kind. Any
+breach terminates all permissions immediately. Contact: https://DFKlabs.com.