This repository contains the static website for the Bitty project. It renders
the marketing shell plus the canonical documents whose frontmatter sets
website_publish: true, consumed from four pinned source revisions. It does not
publish product features, search, analytics, localized content, or an
unversioned routing contract.
Canonical technical documentation remains owned by its corpus: bitty-docs
(governance content and the revision index), bitty-terminal-docs,
bitty-plugins-docs, and bitty-ai-docs; this repository only mirrors and
presents them. The authoritative mechanism, route mapping, and operator
contract live in the canonical bitty-docs guide
docs/development/website-sync.md (Website Delivery RFC, OQ-023).
The 2026-09-14 project decision selects Astro plus Astro Starlight for the Bitty developer portal at https://bitty.run. Website v1 ships a CSS-only theme on the current Astro shell instead: home page, docs entry points, an inline-SVG architecture sketch, and push-to-main Cloudflare auto-deploy. Starlight adoption, UI/UX, internationalization, themes beyond this CSS layer, and search stay deferred to the 0.1.0 release window. The canonical Website Delivery RFC still lists a required Starlight theme as deferred; recording the target here does not change that contract, and the presentation decision must be accepted before migration work starts.
Target site map (v1 routes / and /docs/...; the rest stays planned):
| Route | Planned purpose |
|---|---|
/ |
Home (v1): usage, configuration, and architecture entry points plus an inline-SVG sketch |
/docs/... |
Getting started, configuration, keybindings, panels, IPC, Lua, architecture |
/api/... |
Lua, plugin, and IPC reference |
/plugins/ |
Entry point that links or redirects to https://plugins.bitty.run |
/ai/ |
AI subsystem documentation |
/blog/, /changelog/ |
Announcements and release history |
The plugin store is a separate Vite application at
https://plugins.bitty.run; it is not built, deployed, or documented from this
repository. Canonical content is aggregated at build time from four pinned
sources — bitty-docs, bitty-terminal-docs, bitty-plugins-docs, and
bitty-ai-docs — each mounted under its own route prefix; see
content-sources/README.md and src/content/docs-revision.json. /api/,
/ai/, and the remaining planned routes above are still deferred: aggregation
keeps every corpus under /docs/<version>/....
astro.config.mjs records the canonical origin as
site: "https://bitty.run". Pushes to main auto-deploy dist/ through
wrangler using the organization CLOUDFLARE_ACCOUNT_ID and
CLOUDFLARE_API_TOKEN secrets (see .github/workflows/deploy.yml); no
production deploy happens from a pull request. i18n/ remains a documented
placeholder for the deferred locale layout;
content-sources/ documents the implemented source-aggregation layout and
holds no fetched content (the mirror is generated).
CarryCtx is the local-first tool that records this project's tasks, decisions, and checkpoints. Install it globally for local development (recommended):
cargo install carryctx # Rust toolchain, or: npm i -g carryctxCarryCtx engineering state (tasks, sessions, checkpoints) is not cloned. A
fresh clone restores it from the in-repo refs/heads/carryctx-snapshots
branch:
just workflow-import-dry # fetch + validate the snapshot; no DB writes
just workflow-import # initialize CarryCtx state if needed, then importThen carryctx stats reports the restored tasks, sessions, and checkpoints.
Provenance, redaction, and --force behavior are covered under the
repository snapshot documentation below.
- Bun 1.4.2
- just
- actionlint 1.7.12
Install the exact dependency graph recorded in bun.lock:
bun install --frozen-lockfileRun the same logical quality gates used by CI:
just checkThe aggregate check verifies formatting, Markdown linting, the docs mirror
staleness gate, TypeScript 7.0.2 with its native compiler, the Astro static
build, the expected dist/index.html output, Wrangler's deployment
configuration in dry-run mode, and both GitHub Actions workflows. The
validate:dist script also checks the emitted cache-header contract and the
generated dist/docs-provenance.json corpus record.
Cloudflare Workers Static Assets reads public/_headers from the build
output. Content-hashed /_astro/* assets use a one-year immutable browser
cache, while /icons/* and the root HTML document retain
public, max-age=0, must-revalidate so content updates are revalidated.
Never edit src/content/docs/ by hand: it is a generated, read-only mirror of
the four pinned corpus revisions. The pins live in
src/content/docs-revision.json (schema 2, one entry per source with its mount
and published band); src/content/docs-manifest.json records the per-source
parity results, counts, per-file provenance (source path, SHA-256, revision),
and the routes each source publishes. content-sources/README.md describes the
model and the documentation gates (docs-check, docs-sync, validate:dist).
Advance one source to a merged, reviewed commit, or re-materialize every source at its committed pin:
just docs-sync # re-materialize all four sources (idempotent)
just docs-sync --source bitty-docs --pin <sha> # advance exactly one source
just docs-check # fail-closed staleness gatejust check runs docs:check, so CI fails when the mirror or manifest drifts
from a pinned source or was hand-edited. Canonical documentation is the
source and must be recorded continuously: a docs change is not complete until
the owning corpus's pin advances in the same delivery window. See the canonical
operator note for the full procedure.
Git hooks managed by lefthook enforce Conventional Commits messages and
pre-commit formatting plus Markdown linting on staged files. Install them once
per clone with just hooks-install; every hook runs through a justfile target.
Astro 7.2.6 cannot currently run astro check with TypeScript 7 because its
language service depends on a programmatic API that the native compiler does
not yet expose. The native TypeScript check does not replace Astro's full
language-server diagnostics; the static build separately compiles the Astro
template. Upstream support is tracked in the official
Astro TypeScript 7 compatibility discussion.
Restoring the full Astro diagnostics gate requires a separately reviewed task
after that support is available.
Use just fmt only when intentionally updating formatting. Generated build and
Wrangler dry-run output are not repository content.
CarryCtx runtime state (.git/carryctx/state.sqlite) is never cloned. The
redacted engineering snapshot lives in this repository on branch
refs/heads/carryctx-snapshots, one commit per publication. The commander's
merge closeout publishes it with just workflow-publish; a fresh clone restores
its local CarryCtx DB from that branch:
just workflow-import-dry # fetch + validate the snapshot; no DB writes
just workflow-import # initialize CarryCtx state if needed, then importThe import fetches refs/heads/carryctx-snapshots, refuses to replace a
non-empty local DB without --force (just workflow-import --force), and
prints provenance (snapshot commit + source). Snapshots are redacted
publication artifacts produced by carryctx export --publication: CarryCtx
refuses them as merge sources, so restore always uses replace mode, and a
secret that leaked before rotation must still be rotated at the source.
The deployment workflow is manual, restricted to the main branch, and guarded by the production environment. Its presence is configuration only: no deployment has been performed or verified by this bootstrap. The canonical origin for the portal is https://bitty.run; domain verification through Cloudflare is still pending, and deploy or release automation changes are deferred to the 0.1.0 window under a scoped task.
The workflow references the approved GitHub secret names only at the deployment step. Never place credential values in source files, command arguments, logs, artifacts, or task records.