beadcyte 0.4.0

package/README.md

@@ -0,0 +1,386 @@
+<img src="docs/beadcyte-mark.png" alt="beadcyte" width="380">
+
+<!-- hand-maintained: start -->
+<!-- Written by the maintainer, not by agents. See CLAUDE.md. -->
+
+A local web-based history and projected future, for any
+[beads](https://github.com/gastownhall/beads) project.
+
+Pairing agents with beads has changed how our team works: far more is in flight than before. However, velocity in one place exposes bottlenecks in another. **If production of ideas becomes cheap, managing the flow of ideas becomes critical**. This tool is for teams using beads to coordinate with agents over long-horizon tasks. [The feature tour](#the-tour) below walks through each view.
+
+beadcyte reads your beads DB with `bd list --all --json` and draws two things that look alike and are not: what **happened**, which is measured, and what it **expects to happen**, which is a model's opinion. Three models drive the projection: a historical-median duration estimator, a greedy WIP-cap scheduler calibrated against your real throughput, and an eight-signal triage score. Each is shown with its own uncertainty rather than as a flat number.
+
+beadcyte is made by [Incyte Studios](https://incytestudios.com).
+
+<!-- hand-maintained: end -->
+
+---
+
+## Quick start
+
+```bash
+cd /path/to/your/beads/project
+npx beadcyte start
+```
+
+That opens an interactive app on `127.0.0.1:4173` and gives you the terminal
+back; `npx beadcyte stop` ends it. Localhost only, no auth, no build step —
+same threat model as `bv`.
+
+Or install it once; `bcyte` is a short alias for the same command:
+
+```bash
+npm i -g beadcyte
+beadcyte start
+```
+
+For a single self-contained SVG, with no server:
+
+```bash
+beadcyte --out gantt.svg
+```
+
+The SVG has a system font stack and no external references, so it embeds
+anywhere: MR comments, wiki pages, dashboards.
+
+---
+
+## The tour
+
+### Mine — what should I be doing, what is going on
+
+![The mine view](docs/screenshots/mine.png)
+
+The first tab, and the one the app opens on. Everything on it is about one
+person: what is ready for you (assigned to you, approved with `spec:ready`,
+not already moving, every blocker closed), what you have in progress and in
+review, which of your beads are waiting on someone else and who that is,
+whose beads are waiting on you, and what you are watching. Unassigned beads
+the scheduler would route to you appear as suggestions, marked as inferred.
+
+Who "you" are is set once, in the options menu, from the assignees present in
+the data, and remembered by the browser. A shared link carrying `?me=` shows
+that person's view for one load without changing your own choice. Until a
+user is chosen, the view asks.
+
+The same two questions are one click away on the Gantt and grid too: the
+MINE buttons in the controls row set the filters to *my ready work* or *my
+work in review* outright, so the result never depends on what was selected
+before, and clicking the active one clears back to the defaults. The
+`unblocked` term they rely on is an ordinary filter as well.
+
+### Gantt — history and projection on one timeline
+
+![The Gantt view](docs/screenshots/gantt.png)
+
+Past bars are real `started_at → closed_at`. Future bars are the scheduler's
+projection, and their length is a bucketed median of how long comparable work
+has actually taken. A dashed red rule marks today, group headers carry a
+progress chip, and dependency arrows connect `blocks` edges between visible
+bars.
+
+Bar styling distinguishes the cases that matter: shipped work carries a ship
+marker, closed-without-shipping is dim, backlog beads that are not
+`spec:ready` are faint, and a bar whose assignee the scheduler **guessed** by
+affinity is hatched — with the lane header counting how many of its beads are
+guesses — rather than presented as a decision. In the
+screenshot ten of this repo's 40 closed beads are dim for a real reason: they
+were closed without ship evidence, so nothing says they shipped.
+
+The footer under the chart counts bars by kind, and each name explains
+itself on hover: `shipped` and `closedNoShip` are history; `inProgressLive`
+is the spent part of work under way; `future`, `futureBacklog` (not
+`spec:ready`, scheduled after the ready work) and `unassigned` (from the pool
+nobody owns) are the projection. A projected bar is the **work**, to scale.
+The waiting around it — unclaimed time before an affinity pick, review time
+before the landing — is drawn dull, hatched and cut short at the date it ends,
+with a dotted connector for what was cut: its length is not to scale, its
+end is. The tooltip gives both numbers.
+
+Status is one control, not two: the filter starts with every status except
+closed and deferred selected, and the panel says `3 selected` rather than
+leaving you to infer a default from an empty chip.
+
+Hovering a bar gives the bead's detail and a projected finish **date** — not a
+day offset — including whether that date is a projection or just the end of the
+scheduling window.
+
+A window that would squeeze below six pixels a day scrolls instead: the plot
+shows a readable span centred on today, with a scrollbar under it. Drag the
+axis to pan, wheel over the axis to zoom, swipe or shift-wheel over the plot
+to pan, and `t` brings today back to the centre. A window that fits is drawn
+whole, as before.
+
+### Grid — browse without the time axis
+
+![The grid view](docs/screenshots/grid.png)
+
+The same filtered set as cards: title, chips, assignee, labels. Better than the
+Gantt for reading titles and worse for anything about time, which is why both
+exist.
+
+### Table — every derived number in one sortable place
+
+![The table view](docs/screenshots/table.png)
+
+The same filtered set as dense rows, one per bead, with everything the app
+knows in columns: type, priority, status, assignee (marked when the scheduler
+inferred it), labels, estimate, projected finish, triage score, group. Every
+column sorts; the default is triage score, highest first, because the table's
+job is "what next". Unlike the Gantt it never drops rows to keep a group
+short, so it is also the readable equivalent of the chart — nothing in the app
+is reachable only by reading a bar.
+
+### Incytes — the project, not the beads
+
+![The incytes view](docs/screenshots/incytes.png)
+
+Ships per week over the velocity window, per-group completion sorted by size
+so the outlier is findable, and Allocation: everyone's work in flight against
+their calibrated cap on one shared scale, with the run past the cap drawn at
+its real length. That block used to sit under the controls on every view; it
+is a project-wide fact, so it lives here.
+
+Beside the ship trend, **Cost per week**: seat hours stacked by seat, with
+tokens in and out in the figures and the table, in the same weekly buckets.
+Weeks behind today are what closed beads recorded; weeks ahead are projected
+from the median cost of comparable shipped work, placed where the schedule
+lands each bead, and drawn dulled and dashed so they cannot be read as
+measured. The same block appears on a person's pane for their beads. See
+[docs/economics.md](docs/economics.md#cost-trajectory) for exactly how.
+
+**This screenshot is beadcyte's own repo, and the spike is the honest shape
+of recovered data.** Nothing here recorded a ship while the work happened; the
+evidence was read back out of `Closes <id>` commit trailers afterwards, so
+every ship lands in the week the trailers exist and the seven weeks before it
+are structurally zero — the repo did not exist.
+
+Which is why the headline says _"first week of history — no baseline yet"_
+rather than `+700%`. With one shipping week the mean **is** that week divided
+by the window length, so a percentage against it is decided by the window and
+not by the work: identical beads report +700% at ±90d and +300% at ±30d. A
+number that moves when you change the axis is an artefact with a percent sign
+on it, so the chart declines to print one.
+
+If your own trend looks empty rather than spiky, nothing is broken and nothing
+was recorded — see [what to record](docs/economics.md#what-counts-as-ship-evidence).
+
+Pick a person — the chips at the top of the view, a swimlane header when
+grouped by assignee, a handle on a grid card or in the Allocation block — and
+the same two charts re-scope to them: their ships per week in the project's
+weeks, and the progress of the beads recorded as theirs. Below that, their
+roster line (the raw cap, the calibrated cap and how it was derived, or a
+plain statement that no roster was written and the cap is a default), what is
+in flight, what is ready for them, what the scheduler would route to them
+next — marked as a projection, because nobody decided it — and their recent
+ships. `?who=` carries the selection in the link.
+
+Two more blocks on that pane are the plan's edge for the person. **Frontier**
+is a ruler of the coming days — the window's forward span, 7 to 60 — with a
+hollow mark where a bead starts for them and a filled one where it lands,
+read off the same schedule the Gantt draws; dashed marks are assignments the
+scheduler inferred. **Proposed next** ranks what they could take, with the
+reasons stated beside each: the scheduler's own routing, roster affinity,
+triage score, what it unblocks, priority, whether they have room today — and,
+where someone else is over cap, that person's not-yet-started beads offered
+across. Stage puts a proposal into the what-if (below), where the diff shows
+what moves; nothing is written until it is confirmed.
+
+### The drawer — why a bead ranks where it does
+
+![The bead drawer](docs/screenshots/drawer.png)
+
+Triage's eight signals as contribution meters. The track length is the
+signal's declared weight, so a signal that could never matter much is visibly
+short. The fill is what this bead actually contributed. A tick marks what a
+high value looks like on **your** repo, and a cut-off track marks weight the
+signal cannot reach at all.
+
+Signals that cannot separate anything on your data are labelled `FLAT` — one
+of them carries the second-largest weight and is frequently non-zero on
+exactly one bead, because shallow dependency graphs give it nothing to measure.
+An authoritative-looking number that means nothing is worse than no number, so
+the drawer says which is which. Below that: the dependency subgraph — for an
+epic, the graph of all its children and the blocks edges between them, since
+an epic's own neighbourhood is just the epic, with a full-screen view for the
+large ones — the dossier with projected dates, and where the bead's time went.
+
+That last one distinguishes what was **measured** from what beadcyte
+**computed**. The queue wait is `started_at − created_at`, arithmetic on
+fields `bd` maintains for free, so it is derived wherever nobody recorded it —
+hatched, and its legend row tagged `DERIVED`, because a reconstructed number
+that looks measured is one you can never separate out again. Worked hours are
+never derived: the estimator prefers them over wall-clock, so an invented
+figure would override the one real signal rather than diluting it.
+
+Every derived figure in the drawer explains itself. A dotted underline marks
+a term that will: the score, each of the eight signal names, the estimate's
+source (`(feature), n=8` — n is the sample count behind the median, and a
+small one deserves less trust), the projected finish and why it sometimes says
+_finishes after_, the phase names, the tense of the dependency headings, and
+the synthetic-assignee marker. Hover shows the sentence; Tab reaches it; a
+click or tap pins it; Escape, a scroll or a tap elsewhere dismisses it. The
+sentences come from the modules that compute the figures, so a formula cannot
+change without its explanation changing beside it.
+
+### First run
+
+The first visit opens a short walkthrough in the corner — the bar kinds, the
+projection being a model rather than a plan, triage, the views, the controls.
+It is not a modal and takes no focus; skip or finish it and it never returns
+unasked. The options menu re-opens it, and nothing in it exists only there.
+
+### What if
+
+Stage changes without writing them: reassign, reprioritise or mark
+`spec:ready` from a bead's drawer, change someone's cap from their roster
+line on incytes, or add an idea with a rough size from the what-if panel.
+Every plan-reading view then shows the plan as it would be — the Gantt draws
+each moved bead's old work as a dashed ghost with the delta beside it — and
+the panel lists what moves and by how much, where ideas land, and the
+frontier: how many beads land for each person in the next two weeks, before
+and after. Discard drops it all. Confirm shows the `bd` commands the change
+set amounts to, then runs them one after another through the same
+whitelisted endpoint the quick actions use, and reports what happened to
+each; a cap is a roster.json edit and is reported rather than written.
+
+### Acting on a bead
+
+Right-click a bar, a card, a table row or a mine row — or press `a` with the
+drawer open — for the quick actions the allocate ritual otherwise runs through
+the CLI: claim, assign to someone on the roster, mark or remove `spec:ready`,
+add a label, defer. Each runs one
+`bd` command on the server; [How beadcyte uses bd](docs/bd-usage.md) lists
+every one of them and how to reverse it by hand. Nothing else writes to your
+tracker; there is no bulk action and no client-side undo, by design.
+
+### Options — projects, current user, theme, refresh
+
+![The options menu](docs/screenshots/options.png)
+
+Switch between local beads projects, say who you are for the mine view, pick
+light/dark/system and one of twelve styles with live previews — including
+ports of Catppuccin, Dracula, GitHub, Gruvbox, Nord, One, Solarized and Tokyo
+Night, and a High Contrast original — and set the poll interval. A project the current server
+cannot read is shown as unavailable with the reason, rather than failing when
+you click it.
+
+---
+
+### Keyboard
+
+Press `?` for the shortcuts. The convention is single letters with no
+modifier — `j`/`k` walk the beads in view, `1`–`5` switch views, `g` and
+`w` cycle group-by and window, `p` pins, `,` opens options — and nothing
+fires while you are typing in a field. The keyboard cursor is the open drawer:
+there is no separate focused row, so exactly one thing ever looks selected.
+The overlay is generated from the same table that binds the keys, so it cannot
+drift from them.
+
+## Flags
+
+`beadcyte [flags]` — SVG mode:
+
+| Flag                 | Default                 | Meaning                                |
+| -------------------- | ----------------------- | -------------------------------------- |
+| `--from -Nd`         | `-90d`                  | Window start, relative to today        |
+| `--to +Nd`           | `+90d`                  | Window end, relative to today          |
+| `--group-by MODE`    | `epic`                  | `epic` / `assignee` / `seat` / `track` |
+| `--max-per-group N`  | `20`                    | Rows per swimlane before truncation    |
+| `--include-deferred` | `false`                 | Include `status=deferred` beads        |
+| `--roster PATH`      | `.beadcyte/roster.json` | Per-project WIP caps and affinities    |
+| `--out PATH`         | `./beadcyte.svg`        | SVG output path                        |
+
+`beadcyte changelog [flags]` — regenerate `CHANGELOG.md` from closed beads:
+
+| Flag       | Meaning                                     |
+| ---------- | ------------------------------------------- |
+| _(none)_   | Write `CHANGELOG.md` at the repo root       |
+| `--check`  | Exit 2 if the committed file is out of date |
+| `--stdout` | Print instead of writing                    |
+
+An entry appears when a closed bead carries ship evidence. Spikes, `upstream:`
+bugs, chores and epics are excluded, and releases are cut by git tag — the
+file states both rules in its own header, so a reader can tell "nothing
+shipped" from "this file does not list that".
+
+`beadcyte start [flags]` — interactive mode. Starts the server in the
+background, prints its address and the log path, and returns; `beadcyte stop`
+ends it, from the same directory. `beadcyte serve [flags]` runs the same server
+in the foreground instead, with Ctrl-C to stop. Both take the same flags:
+
+| Flag             | Default                 | Meaning                             |
+| ---------------- | ----------------------- | ----------------------------------- |
+| `--port N`       | `4173`                  | Listen port; falls through if taken |
+| `--roster PATH`  | `.beadcyte/roster.json` | Same roster convention              |
+| `--cache-ttl MS` | `30000`                 | `bd` shell-out cache TTL            |
+
+The version tag in the header opens the changelog, rendered in the app from
+the copy shipped with the build. Set `BEADCYTE_CHANGELOG_URL` to add a link out
+to the same file on your repo; it is absent when unset.
+
+Most of the interactive app's state lives in the URL — view, grouping,
+filters, window — so a link shares what you were looking at. Links written
+before the status filter absorbed the old `showClosed` / `includeDeferred`
+toggles still resolve to the same view.
+
+---
+
+## Documentation
+
+|                                     |                                                                                                                                        |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [What to record](docs/economics.md) | What beadcyte reads out of your beads, what breaks when it is missing, and how to record it. **Start here if your charts look empty.** |
+| [The model](docs/model.md)          | How the estimator, the scheduler and the triage score work, what they are calibrated against, and where they are known to be wrong.    |
+| [How beadcyte uses bd](docs/bd-usage.md) | Every `bd` command the app runs — the reads, the background history walk, each quick action and how to reverse it — and whose name a claim carries. |
+| [Roster](docs/roster.md)            | Per-project WIP caps and affinity routing.                                                                                             |
+| [Programmatic use](docs/api.md)     | Using the estimator and scheduler as libraries.                                                                                        |
+| [Theming](docs/theming.md)          | The token layer, light/dark, named styles, and the audit that keeps a restyle from relabelling the data.                               |
+| [CHANGELOG](CHANGELOG.md)           | What has shipped. Generated from the tracker, not written by hand.                                                                     |
+
+---
+
+## Development
+
+```bash
+npm install
+npm run dev          # beadcyte serve against this repo's own beads (port 4173)
+npm test                  # unit + parity + perf suites
+npm run typecheck         # vue-tsc --noEmit
+npm run build             # static bundle → src/web/dist
+npm run changelog         # regenerate CHANGELOG.md
+npm run changelog:check   # fail if the committed CHANGELOG.md is stale
+```
+
+`npm run dev` points the dev server at beadcyte's own beads DB, so the app is
+always dogfooding itself.
+
+---
+
+## Non-goals
+
+- **Resource-constrained scheduling.** Greedy dispatch, no solver. No
+  cross-human load balancing and no auto-reassignment: the chart is a
+  projection of current allocation, not a proposal for a better one.
+- **Drag-editing the plan.** Dates come from the model; changing them means
+  changing the beads.
+- **Non-`bd` trackers.** The input shape is `bd list --json`; anything else
+  needs an adapter.
+
+## Licence
+
+AGPL-3.0-only. See [LICENSE](LICENSE).
+
+beadcyte is copyright [Incyte Studios, LLC](https://incytestudios.com) and released under the GNU Affero
+General Public License, version 3. You may use, change and redistribute it
+under the same terms. If you run a modified version as a network service,
+section 13 obliges you to offer its users the corresponding source.
+
+Incyte Studios stays the sole copyright holder so that it can also offer the
+project under other terms. That is why contributions are accepted under a
+permissive inbound licence rather than the AGPL; see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+Dependencies are MIT, ISC, BSD and Apache-2.0 licensed and carry their own
+notices. The triage score is a local reimplementation of a formula documented
+by another tool, not a copy of its code; see [docs/model.md](docs/model.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,56 @@
+# Third-party notices
+
+beadcyte is released under AGPL-3.0-only (see [LICENSE](LICENSE)). The named
+colour styles in `src/web/styles-ported.css` reproduce palette values published
+by the projects below, each under the MIT licence. Palette values are facts
+rather than copyrightable expression, but the values were copied from licensed
+files, so the copyright line and permission notice of each are reproduced here
+as that licence asks. Theme names belong to their owners and are used only to
+identify the palette a style reproduces.
+
+The Default, Synthwave, Terminal and High Contrast styles are beadcyte's own.
+
+## MIT License
+
+The following applies to each project in the table, with the copyright line
+shown for it:
+
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in
+> all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+
+| Style | Project | Copyright | Licence source | Palette source |
+| --- | --- | --- | --- | --- |
+| Catppuccin | [catppuccin/palette](https://github.com/catppuccin/palette) | Copyright (c) 2021 Catppuccin | [LICENSE](https://github.com/catppuccin/catppuccin/blob/main/LICENSE) | `palette.json`, Mocha and Latte flavours |
+| Dracula | [dracula/dracula-theme](https://github.com/dracula/dracula-theme) | Copyright (c) 2023 Dracula Theme | [LICENSE](https://github.com/dracula/dracula-theme/blob/master/LICENSE) | README colour palette tables, Dracula and Alucard |
+| GitHub | [primer/primitives](https://github.com/primer/primitives) 7.11.13 | Copyright (c) 2018 GitHub Inc. | [LICENSE](https://github.com/primer/primitives/blob/main/LICENSE) | `dist/json/colors/light.json` and `dark.json` |
+| Gruvbox | [morhetz/gruvbox](https://github.com/morhetz/gruvbox) | Pavel Pertsev | `"license": "MIT"` in [package.json](https://raw.githubusercontent.com/morhetz/gruvbox/master/package.json); the repository ships no LICENSE file | `colors/gruvbox.vim` |
+| Nord | [nordtheme/nord](https://github.com/nordtheme/nord) | Copyright (c) 2016-present Sven Greb | [license](https://github.com/nordtheme/nord/blob/develop/license) | `src/nord.css`, `--nord0` to `--nord15` |
+| One | [atom/one-dark-syntax](https://github.com/atom/one-dark-syntax) and [one-light-syntax](https://github.com/atom/one-light-syntax) | Copyright (c) 2016 GitHub Inc. | [LICENSE.md](https://github.com/atom/one-dark-syntax/blob/master/LICENSE.md) | `styles/colors.less` in each, authored as HSL |
+| Solarized | [altercation/solarized](https://github.com/altercation/solarized) | Copyright (c) 2011 Ethan Schoonover | [LICENSE](https://github.com/altercation/solarized/blob/master/LICENSE) | README palette table |
+| Tokyo Night | [enkia/tokyo-night-vscode-theme](https://github.com/enkia/tokyo-night-vscode-theme) | Copyright (c) 2018-present Enkia | [LICENSE.txt](https://github.com/enkia/tokyo-night-vscode-theme/blob/master/LICENSE.txt) | `themes/tokyo-night-color-theme.json` and the light variant |
+
+## What was changed
+
+A port keeps each theme's hues. Where a published colour fell short of
+beadcyte's legibility floors it was moved in lightness only, and the lightness
+of every colour-only encoding token was then placed by
+`scripts/place-encoding-lightness.mjs` so each pair stays distinguishable under
+simulated colour-vision deficiency. Two named substitutions go further and are
+noted above their blocks in `src/web/styles-ported.css`: Nord's bar hues carry
+scaled chroma, and Solarized's future bars use its magenta rather than its
+violet. The derivation rules are in [docs/theming.md](docs/theming.md).

package/bin/beadcyte.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// beadcyte — CLI dispatcher. The package is published unscoped as `beadcyte`
+// so `npx beadcyte start` works from any beads project. A global install puts
+// two names on PATH for the same file: `beadcyte`, and `bcyte` for short.
+//
+// Subcommands:
+//   beadcyte                → default SVG mode (see src/cli.mjs)
+//   beadcyte export [args]  → alias for the default SVG mode
+//   beadcyte start  [args]  → serve in the background, print the address, return
+//   beadcyte stop           → end the background server for this directory
+//   beadcyte serve  [args]  → the same server in the foreground (see src/serve.mjs)
+//   beadcyte changelog      → generate CHANGELOG.md from closed beads
+//   beadcyte --help         → passes to whichever subcommand's --help
+//   beadcyte --version      → prints the version from package.json
+//
+// A subcommand is the FIRST positional arg with no leading `--`. Flags stay
+// in their subcommand's argv slice; `beadcyte --from -30d` is the default subcommand
+// with `--from -30d`, not a subcommand called `--from`.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+const argv = process.argv.slice(2);
+const first = argv[0];
+const KNOWN_SUBCOMMANDS = new Set(["start", "stop", "serve", "export", "changelog"]);
+
+// Handle version flag first
+if (first === "--version" || first === "-v") {
+  console.log(packageJson.version);
+  process.exit(0);
+}
+
+if (first === "serve") {
+  process.argv = [process.argv[0], process.argv[1], ...argv.slice(1)];
+  await import("../src/serve.mjs");
+} else if (first === "start") {
+  process.argv = [process.argv[0], process.argv[1], ...argv.slice(1)];
+  await import("../src/start.mjs");
+} else if (first === "stop") {
+  process.argv = [process.argv[0], process.argv[1], ...argv.slice(1)];
+  await import("../src/stop.mjs");
+} else if (first === "changelog") {
+  process.argv = [process.argv[0], process.argv[1], ...argv.slice(1)];
+  await import("../src/changelog-cli.mjs");
+} else if (first === "export" || first === undefined || first.startsWith("--")) {
+  // default: SVG mode (drop `export` if present)
+  if (first === "export")
+    process.argv = [process.argv[0], process.argv[1], ...argv.slice(1)];
+  await import("../src/cli.mjs");
+} else {
+  console.error(
+    `beadcyte: unknown subcommand "${first}". Try one of: ${[...KNOWN_SUBCOMMANDS].join(", ")}, or omit for the default SVG mode.`,
+  );
+  process.exit(2);
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "beadcyte",
+  "version": "0.4.0",
+  "description": "Gantt of bead history + projected future — historical-median estimator + greedy WIP-cap scheduler + self-contained SVG",
+  "author": "Incyte Studios, LLC <hello@incytestudios.com> (https://incytestudios.com)",
+  "type": "module",
+  "bin": {
+    "beadcyte": "bin/beadcyte.mjs",
+    "bcyte": "bin/beadcyte.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./estimator": "./src/estimator.mjs",
+    "./scheduler": "./src/scheduler.mjs",
+    "./cli": "./src/cli.mjs",
+    "./format": "./src/format.mjs",
+    "./changelog": "./src/changelog.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/**/*.test.mjs",
+    "!src/web/__fixtures__",
+    "!src/web/dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "dev": "node bin/beadcyte.mjs serve",
+    "build": "vite build",
+    "preview": "vite preview",
+    "typecheck": "vue-tsc --noEmit",
+    "test": "node --test 'src/**/*.test.mjs'",
+    "changelog": "node src/changelog-cli.mjs",
+    "changelog:check": "node src/changelog-cli.mjs --check"
+  },
+  "dependencies": {
+    "@incytestudios/ddv": "^1.0.0-rc.4",
+    "@lucide/vue": "^1.39.0",
+    "@vitejs/plugin-vue": "^5.2.1",
+    "@vueuse/core": "^10.11.0",
+    "@vueuse/gesture": "^2.0.0",
+    "date-fns": "^3.6.0",
+    "downsample": "^1.4.0",
+    "marked": "^18.0.11",
+    "pinia": "^2.3.0",
+    "vite": "^5.4.11",
+    "vue": "^3.5.13"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "beads",
+    "bd",
+    "gantt",
+    "scheduling",
+    "svg",
+    "planning"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/incytestudios/beadcyte.git"
+  },
+  "homepage": "https://gitlab.com/incytestudios/beadcyte",
+  "bugs": {
+    "url": "https://gitlab.com/incytestudios/beadcyte/-/issues"
+  },
+  "license": "AGPL-3.0-only",
+  "devDependencies": {
+    "@tsconfig/node20": "^20.1.10",
+    "typescript": "~5.6.3",
+    "vue-tsc": "~2.1.10"
+  }
+}