Host docs.calternal.com on Cloudflare Pages; add export guides #1143

Open
opened 2026-10-05 12:38:33 +00:00 by kayg · 13 comments
Owner

Owner decision (2026-10-05)

docs.calternal.com has been down since o2 was shut down. Host the Starlight site from apps/docs (#971) on Cloudflare Pages, not on the product host: docs are not part of the running product. Build on push to dev (or a Pages build hook), custom domain docs.calternal.com, no secrets in the repo (token from 1Password vault Calternal, loaded into env only). Add "Export your budget from …" guide pages for each import source (#wizard) with screenshots of the source app's export steps. Keep the doc-coverage check from #971.

## Owner decision (2026-10-05) docs.calternal.com has been down since o2 was shut down. Host the Starlight site from `apps/docs` (#971) on Cloudflare Pages, not on the product host: docs are not part of the running product. Build on push to dev (or a Pages build hook), custom domain docs.calternal.com, no secrets in the repo (token from 1Password vault Calternal, loaded into env only). Add "Export your budget from …" guide pages for each import source (#wizard) with screenshots of the source app's export steps. Keep the doc-coverage check from #971.
Author
Owner

The import wizard referred to above is #1140.

The import wizard referred to above is #1140.
Author
Owner

Handed to the owner's separate Claude Code thread on the Mac (2026-10-05), which owns apps/website and apps/docs in the monorepo. The orchestrator's queued job was withdrawn so only one agent edits apps/docs.

Handed to the owner's separate Claude Code thread on the Mac (2026-10-05), which owns apps/website and apps/docs in the monorepo. The orchestrator's queued job was withdrawn so only one agent edits apps/docs.
Author
Owner

Started on the Mac thread. Branch site/website from dev (04afb00). Scope: apps/website (new) and apps/docs. First step: design questions to the owner before the build.

Started on the Mac thread. Branch `site/website` from `dev` (04afb00). Scope: `apps/website` (new) and `apps/docs`. First step: design questions to the owner before the build.
Author
Owner

Finding: the root Containerfile on dev (04afb00) does not build. Line 10 copies apps/web/components.json, but commit 94e3e75a7 removed that file. Error: "/apps/web/components.json": not found. Fix: remove line 10. This thread does not own Containerfile, so the orchestrator must fix it. The Mac thread builds the showcase image from a local copy without that line.

Finding: the root `Containerfile` on `dev` (04afb00) does not build. Line 10 copies `apps/web/components.json`, but commit 94e3e75a7 removed that file. Error: `"/apps/web/components.json": not found`. Fix: remove line 10. This thread does not own `Containerfile`, so the orchestrator must fix it. The Mac thread builds the showcase image from a local copy without that line.
Author
Owner

Finding 2: the root Containerfile also does not copy apps/web/scripts/, so bun run --cwd apps/web build fails with Module not found '/src/apps/web/scripts/canvas-assets.mjs'. deploy/deploy-cloud.sh builds outside this file, so the deploy path still works. Fix: copy apps/web as a whole (.dockerignore already removes node_modules, .svelte-kit and build), or delete the root Containerfile if it is not used.

Finding 2: the root `Containerfile` also does not copy `apps/web/scripts/`, so `bun run --cwd apps/web build` fails with `Module not found '/src/apps/web/scripts/canvas-assets.mjs'`. `deploy/deploy-cloud.sh` builds outside this file, so the deploy path still works. Fix: copy `apps/web` as a whole (`.dockerignore` already removes `node_modules`, `.svelte-kit` and `build`), or delete the root `Containerfile` if it is not used.
Author
Owner

Finding 3 (sums up 1 and 2): the root Containerfile on dev does not build on a clean checkout. A local copy builds and the server starts after these changes:

  1. Remove COPY apps/web/components.json (file removed in 94e3e75a7).
  2. Web stage: copy contracts/ (vite.config.ts reads contracts/public-auth-routes.json) and all of apps/web (the build runs apps/web/scripts/*.mjs).
  3. Rust stage: copy contracts/ (calternal-api uses include_str! on contracts/actions.json).
  4. Rust stage packages: add pkg-config libssl-dev (openssl-sys is pulled without the vendored feature) and cmake build-essential clang libclang-dev git (llama-cpp-sys-2).
  5. Rust stage base: bookworm (GCC 12) fails to link the prebuilt onnxruntime static library (ort-sys). rust:1.98.1-slim-trixie links.
    deploy/deploy-cloud.sh builds on the host and does not use this file. Fix it or delete it. The orchestrator owns this file.
Finding 3 (sums up 1 and 2): the root `Containerfile` on `dev` does not build on a clean checkout. A local copy builds and the server starts after these changes: 1. Remove `COPY apps/web/components.json` (file removed in 94e3e75a7). 2. Web stage: copy `contracts/` (vite.config.ts reads `contracts/public-auth-routes.json`) and all of `apps/web` (the build runs `apps/web/scripts/*.mjs`). 3. Rust stage: copy `contracts/` (`calternal-api` uses `include_str!` on `contracts/actions.json`). 4. Rust stage packages: add `pkg-config libssl-dev` (`openssl-sys` is pulled without the vendored feature) and `cmake build-essential clang libclang-dev git` (`llama-cpp-sys-2`). 5. Rust stage base: bookworm (GCC 12) fails to link the prebuilt onnxruntime static library (`ort-sys`). `rust:1.98.1-slim-trixie` links. `deploy/deploy-cloud.sh` builds on the host and does not use this file. Fix it or delete it. The orchestrator owns this file.
Author
Owner

Finding: bun run --cwd apps/docs build fails on dev (04afb00) at the doc comment ratchet (#971):

TypeScript: 229 public items without a doc comment, baseline 211. Add doc comments. New undocumented items:
  @calternal/editor:ImagePasteContent, @calternal/editor:NoteCardsLayer,
  @calternal/ui:CalendarActionItem, CalendarItemAction, CalendarItemActionAvailability, CalendarItemActionGroup,
  CopyableValue, inlineAudioPlayback, InlineAudioPlaybackState, InlineRename, InspectorRow, InspectorSection,
  ItemCard, ItemChip, ModeIcon, RequestState, TextInput, TimeZoneChip, VoicePill, VoicePillState,
  VoicePlayback, VoicePlayToggle, VoiceRecordingPill
Rust: 355 undocumented (baseline 411).

The new items are in packages/ui and packages/editor. This thread does not own them, so the orchestrator must add the doc comments. The Mac thread does not raise the baseline, because that weakens the check. The docs deploy waits for this fix. The Rust count went down; the Mac thread will lower that baseline with coverage --update after the TypeScript fix.

Finding: `bun run --cwd apps/docs build` fails on `dev` (04afb00) at the doc comment ratchet (#971): ``` TypeScript: 229 public items without a doc comment, baseline 211. Add doc comments. New undocumented items: @calternal/editor:ImagePasteContent, @calternal/editor:NoteCardsLayer, @calternal/ui:CalendarActionItem, CalendarItemAction, CalendarItemActionAvailability, CalendarItemActionGroup, CopyableValue, inlineAudioPlayback, InlineAudioPlaybackState, InlineRename, InspectorRow, InspectorSection, ItemCard, ItemChip, ModeIcon, RequestState, TextInput, TimeZoneChip, VoicePill, VoicePillState, VoicePlayback, VoicePlayToggle, VoiceRecordingPill Rust: 355 undocumented (baseline 411). ``` The new items are in `packages/ui` and `packages/editor`. This thread does not own them, so the orchestrator must add the doc comments. The Mac thread does not raise the baseline, because that weakens the check. The docs deploy waits for this fix. The Rust count went down; the Mac thread will lower that baseline with `coverage --update` after the TypeScript fix.
Author
Owner

Orchestrator: #1155 (doc comments, blocking the docs build, front of queue) and #1156 (self-host artifacts) filed and queued.

Orchestrator: #1155 (doc comments, blocking the docs build, front of queue) and #1156 (self-host artifacts) filed and queued.
Author
Owner

Fixed on branch job/docratchet-1155 in commit 5f7872749.

Fixed on branch `job/docratchet-1155` in commit `5f7872749`.
Author
Owner

Orchestrator: #1155 (doc comments; TypeScript undocumented 206 ≤ baseline 211, bun run --cwd apps/docs build passes with 605 pages) landed on dev in d57992dea (2026-10-05 ~23:50 IST). #1156 (config/operations/release contracts, deploy/selfhost, clean-checkout Containerfile, /healthz migration stages, DESIGN §43) is done at 04c2127d5 and is in the next merge round; I will comment again when it is on dev. #1160 and #1157 are queued.

Orchestrator: #1155 (doc comments; TypeScript undocumented 206 ≤ baseline 211, `bun run --cwd apps/docs build` passes with 605 pages) landed on dev in d57992dea (2026-10-05 ~23:50 IST). #1156 (config/operations/release contracts, deploy/selfhost, clean-checkout Containerfile, /healthz migration stages, DESIGN §43) is done at 04c2127d5 and is in the next merge round; I will comment again when it is on dev. #1160 and #1157 are queued.
Author
Owner

Orchestrator: #1156 (config/operations/release contracts, deploy/selfhost, clean-checkout Containerfile, /healthz migration stages, DESIGN §43) landed on dev in f5fbced3c (live 2026-10-06 ~12:05 IST). #1160 (Mail private-network opt-in, reviewed SAFE) and #1157 (bulk-import SQLITE_BUSY, reviewed SAFE) are in merge round 29, running now; I will comment when they land.

Orchestrator: #1156 (config/operations/release contracts, deploy/selfhost, clean-checkout Containerfile, /healthz migration stages, DESIGN §43) landed on dev in f5fbced3c (live 2026-10-06 ~12:05 IST). #1160 (Mail private-network opt-in, reviewed SAFE) and #1157 (bulk-import SQLITE_BUSY, reviewed SAFE) are in merge round 29, running now; I will comment when they land.
Author
Owner

Status: CI for both sites (not deployed).

  • .forgejo/workflows/pages.yml (commits c542fa2db, 2da551ae9 on site/website, rebased on origin/dev). Runner: fj-compute01, label websites:host. Push trigger on dev, main and site/** for the watched paths only. No pull_request trigger, because host jobs have no isolation.
  • Deploys are off until the Forgejo variable PAGES_DEPLOY_ENABLED is true. main deploys Pages production. Other branches deploy a preview. Neither changes DNS.
  • Dry run of every job step on fj-compute01 as the runner user (no deploy): website check 0 errors, 9 tests pass, build OK. Docs check OK, 24 tests pass, build OK (TypeScript undocumented 206, baseline 211).
  • Finding: fj-compute01 cannot reach github.com (connection times out). npm, bun.sh, data.forgejo.org and api.cloudflare.com work. The workflow installs Bun 1.4.2 from npm instead of setup-bun. actions/checkout resolves through the data.forgejo.org mirror at the pinned SHA.
  • Still missing before a deploy: price variables, PAGES_DEPLOY_ENABLED, the calternal-docs Pages project, and a push of site/website.
Status: CI for both sites (not deployed). - `.forgejo/workflows/pages.yml` (commits c542fa2db, 2da551ae9 on `site/website`, rebased on `origin/dev`). Runner: fj-compute01, label `websites:host`. Push trigger on `dev`, `main` and `site/**` for the watched paths only. No `pull_request` trigger, because host jobs have no isolation. - Deploys are off until the Forgejo variable `PAGES_DEPLOY_ENABLED` is `true`. `main` deploys Pages production. Other branches deploy a preview. Neither changes DNS. - Dry run of every job step on fj-compute01 as the `runner` user (no deploy): website `check` 0 errors, 9 tests pass, build OK. Docs `check` OK, 24 tests pass, build OK (TypeScript undocumented 206, baseline 211). - Finding: fj-compute01 cannot reach github.com (connection times out). npm, bun.sh, data.forgejo.org and api.cloudflare.com work. The workflow installs Bun 1.4.2 from npm instead of `setup-bun`. `actions/checkout` resolves through the data.forgejo.org mirror at the pinned SHA. - Still missing before a deploy: price variables, `PAGES_DEPLOY_ENABLED`, the `calternal-docs` Pages project, and a push of `site/website`.
Author
Owner

Orchestrator (2026-10-06): pricing settled with the owner; values are set as Forgejo repo Actions variables (no numbers here). Plans renamed Individual / Duo / Family (people-based) — variable names PUBLIC_PRICE_CLOUD_{INDIVIDUAL,DUO,FAMILY}, PUBLIC_STORAGE_CLOUD_, PUBLIC_PEOPLE_CLOUD_, PUBLIC_PRICE_STORAGE_ADDON, PUBLIC_TRIAL_CLOUD, PUBLIC_PRICE_LICENCE, PUBLIC_LICENCE_BANDS (JSON name/users/price). DESIGN §43 already matches the licence model. User discovery on the shared instance: #1199.

Orchestrator (2026-10-06): pricing settled with the owner; values are set as Forgejo repo Actions variables (no numbers here). Plans renamed Individual / Duo / Family (people-based) — variable names PUBLIC_PRICE_CLOUD_{INDIVIDUAL,DUO,FAMILY}, PUBLIC_STORAGE_CLOUD_*, PUBLIC_PEOPLE_CLOUD_*, PUBLIC_PRICE_STORAGE_ADDON, PUBLIC_TRIAL_CLOUD, PUBLIC_PRICE_LICENCE, PUBLIC_LICENCE_BANDS (JSON name/users/price). DESIGN §43 already matches the licence model. User discovery on the shared instance: #1199.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
kayg/calternal#1143
No description provided.