Docs site at docs.calternal.com: choose framework, skeleton with calternal theming #415

Closed
opened 2026-09-29 09:01:12 +00:00 by kayg · 10 comments
Owner

Goal

Choose a documentation framework for a public docs site at docs.calternal.com, and set up a first skeleton. The owner asked for this on 2026-09-29: "we really gotta make that docs page to record all of this info … a good docs framework (that looks modern and smooth)".

What the site holds

User-facing documentation, written in ASD-STE100 Simplified Technical English:

  • conventions a user must know: the tag grammar (#area/…, #x inside a task becomes #task/x, #403), plaintext file formats (Money Markdown #404, saved places, XMP sidecars), and the file-over-app rules (what is a file and what is derived, owner decision on #341);
  • the Apps surface: API, CLI, MCP, WebMCP (#395);
  • interop setup: CalDAV/CardDAV/WebDAV on Apple devices, profiles;
  • self-hosting and admin.
    docs/DESIGN.md stays the internal decision record. The docs site is for users and self-hosters.

Research (Codex, web search on)

Compare at least these: Starlight (Astro), VitePress, Docusaurus, Fumadocs, Nextra, Rspress, and any SvelteKit-native option that is mature. Leave out proprietary hosted products (Mintlify, GitBook): the licence must be AGPL-3.0-compatible and self-hostable as static files.
For each option, give real evidence:

  • how it looks and moves (take screenshots of each project's own docs at 390 px and 1440 px, light and dark);
  • search (local and offline, for example Pagefind);
  • build time and output size for about 100 pages;
  • Markdown/MDX authoring, versioning and i18n;
  • dark mode;
  • accessibility (keyboard use, screen readers, reduced motion);
  • how easily it takes our tokens (calternal fonts, accent, glass, the springy motion from #291) so the site looks like calternal and not like a stock theme;
  • maintenance activity and licence.

Deliverable

  1. A recommendation with a comparison table and screenshots, posted on this issue.
  2. On the job branch: a skeleton at apps/docs/ using the recommended framework. It needs calternal theming from packages/ui/src/tokens.css (reused, not copied), local search, and 3 real pages ported from DESIGN.md content: tag grammar, file over app, and connecting Apple devices. No placeholder pages (No fake data rule).
  3. A static build that deploy/ can serve later. Do not deploy anything and do not touch DNS. The orchestrator confirms hosting of docs.calternal.com with the owner.
## Goal Choose a documentation framework for a public docs site at `docs.calternal.com`, and set up a first skeleton. The owner asked for this on 2026-09-29: "we really gotta make that docs page to record all of this info … a good docs framework (that looks modern and smooth)". ## What the site holds User-facing documentation, written in ASD-STE100 Simplified Technical English: - conventions a user must know: the tag grammar (`#area/…`, `#x` inside a task becomes `#task/x`, #403), plaintext file formats (Money Markdown #404, saved places, XMP sidecars), and the file-over-app rules (what is a file and what is derived, owner decision on #341); - the Apps surface: API, CLI, MCP, WebMCP (#395); - interop setup: CalDAV/CardDAV/WebDAV on Apple devices, profiles; - self-hosting and admin. `docs/DESIGN.md` stays the internal decision record. The docs site is for users and self-hosters. ## Research (Codex, web search on) Compare at least these: Starlight (Astro), VitePress, Docusaurus, Fumadocs, Nextra, Rspress, and any SvelteKit-native option that is mature. Leave out proprietary hosted products (Mintlify, GitBook): the licence must be AGPL-3.0-compatible and self-hostable as static files. For each option, give real evidence: - how it looks and moves (take screenshots of each project's own docs at 390 px and 1440 px, light and dark); - search (local and offline, for example Pagefind); - build time and output size for about 100 pages; - Markdown/MDX authoring, versioning and i18n; - dark mode; - accessibility (keyboard use, screen readers, reduced motion); - how easily it takes our tokens (calternal fonts, accent, glass, the springy motion from #291) so the site looks like calternal and not like a stock theme; - maintenance activity and licence. ## Deliverable 1. A recommendation with a comparison table and screenshots, posted on this issue. 2. On the job branch: a skeleton at `apps/docs/` using the recommended framework. It needs calternal theming from `packages/ui/src/tokens.css` (reused, not copied), local search, and 3 real pages ported from DESIGN.md content: tag grammar, file over app, and connecting Apple devices. No placeholder pages (No fake data rule). 3. A static build that `deploy/` can serve later. Do not deploy anything and do not touch DNS. The orchestrator confirms hosting of docs.calternal.com with the owner.
Author
Owner

Starting docs-site work on job/docs-site, based on 91231707a18340362ceffc2d53bf8772d44b1db9 (current dev). I have read the repository contract, glossary and design record; I am now checking the source sections and framework evidence before building the site.

Starting docs-site work on `job/docs-site`, based on `91231707a18340362ceffc2d53bf8772d44b1db9` (current `dev`). I have read the repository contract, glossary and design record; I am now checking the source sections and framework evidence before building the site.
Author
Owner

Framework research and recommendation (2026-09-29)

Recommendation: Starlight (Astro). It provides a complete documentation layout, Markdown/MDX/Markdoc, built-in Pagefind search that runs from static files, i18n, light/dark themes, and CSS/component overrides. It lets this site import the existing packages/ui/src/tokens.css and themes.css directly. Rspress is a close alternative, with built-in multi-version navigation; this first skeleton does not need versioned docs. Docusaurus has the most mature first-party versioning, but its documented search relies on Algolia and its measured local-search build is slower. All listed framework licenses are MIT and compatible with the repo license.

Option Writing, search, i18n and versions Theme and accessibility notes License / package activity 100-page static build
Starlight / Astro
overview · Pagefind · authoring · i18n · theming · license · verified package version
Screens: 390 light, 390 dark, 1440 light, 1440 dark
Markdown, MDX, Markdoc; built-in Pagefind local search. i18n built in; no first-party version selector. Responsive docs theme; built-in light/dark. CSS and component overrides; directly importing calternal tokens works. Skip link and keyboard search; screen-reader/reduced-motion behavior still needs an explicit pass. MIT; @astrojs/starlight 0.42.4 (registry modified 2026-09-24). 7.72 s / 4,448,529 B
VitePress / Vue + Vite
overview · local search · i18n · theme config · license · verified package version
Screens: 390 light, 390 dark, 1440 light, 1440 dark
Markdown with Vue components; local MiniSearch. i18n built in; versions need a custom route/build arrangement. Default docs theme has light/dark; theme CSS and Vue components accept tokens. Search dialog has keyboard interaction; screen-reader/reduced-motion audit still required. MIT; 1.6.4 (2026-09-04). 13.46 s / 6,332,649 B
Docusaurus / React
docs · search · versioning · i18n · license · verified package version
Screens: 390 light, 390 dark, 1440 light, 1440 dark
Markdown/MDX; first-party versioning and i18n. Offline search requires a community plugin; Algolia is the first-party documented provider. Dark mode and theme swizzling/CSS allow token mapping. Search is keyboard driven; verify AT and reduced motion in the selected theme. MIT; 3.10.2 (2026-09-25). 58.37 s / 4,734,046 B
Fumadocs / Next.js
static deploy · FlexSearch · layouts · search · license · verified package version
Screens: 390 light, 390 dark, 1440 light, 1440 dark
MDX; FlexSearch static mode for offline search; i18n is available. Version selection is an application-level content/routing choice. Docs, glass and other layouts are provided; React/Tailwind/CSS make token mapping flexible. Dark theme support; test final keyboard/AT behavior. MIT; fumadocs-core/fumadocs-ui 16.15.15 (2026-09-27). 55.31 s / 22,400,389 B
Nextra / Next.js
search · static export · license · verified package version
Screens: 390 light, 390 dark, 1440 light, 1440 dark
MDX; Pagefind can be added for local static search. Locale routes use Next.js; version navigation is custom. Docs theme and dark mode are supplied; CSS/React overrides allow token mapping. Keyboard, AT and reduced motion need an explicit pass. MIT; 4.6.1 (2025-12-04). 145.91 s; static export failed, so no valid output size.
Rspress / Rsbuild
overview · multi-version · license · verified package version
Screens: 390 light, 390 dark, 1440 light, 1440 dark
MDX; built-in offline FlexSearch, i18n and multi-version docs. Default docs theme supports light/dark; CSS and theme component overrides accept tokens. Verify AT and reduced motion in the chosen theme. MIT; 2.0.23 (2026-09-29). 7.58 s / 4,870,886 B
SvelteKit + mdsvex
Svelte packages · adapter-static · mdsvex · license · verified package version
Screens: 390 light, 390 dark, 1440 light, 1440 dark
Markdown with Svelte via mdsvex; Pagefind was added for offline search. i18n, versions and docs UI are custom work. Full control over tokens and motion, but no docs theme; build keyboard, screen-reader and dark-mode behavior as product UI. MIT; SvelteKit 2.70.3, mdsvex 0.12.8, adapter-static 3.0.10. 7.24 s / 1,235,061 B (bare shell, not a full docs theme).

Benchmark method and limits. One local run per option with the same generated 100-page corpus. Install time is excluded. Build time is wall time; output is uncompressed bytes from du -sb, including static search assets. These are single-run numbers on a shared host, not medians. Nextra’s test setup failed to produce a static export after 145.91 s, so it has no comparable size. The SvelteKit number is only a bare mdsvex shell plus Pagefind, without a complete documentation theme, so its output is not like-for-like.

Accessibility evidence. Framework docs do not certify a full screen-reader or reduced-motion experience. The Starlight production build has a skip link and keyboard-opened search. Browser verification confirmed the skip link is the first Tab stop and the reduced-motion media query is active. I did not run a screen reader. The chosen theme still needs an explicit screen-reader and reduced-motion review.

Screenshots of the built site. Captured from the production static build; each link is one page/viewport/theme. The browser pass covered all 4 pages at all widths and both themes. Search on the production preview returned the File over app page from the local Pagefind index.

## Framework research and recommendation (2026-09-29) **Recommendation: Starlight (Astro).** It provides a complete documentation layout, Markdown/MDX/Markdoc, built-in Pagefind search that runs from static files, i18n, light/dark themes, and CSS/component overrides. It lets this site import the existing `packages/ui/src/tokens.css` and `themes.css` directly. Rspress is a close alternative, with built-in multi-version navigation; this first skeleton does not need versioned docs. Docusaurus has the most mature first-party versioning, but its documented search relies on Algolia and its measured local-search build is slower. All listed framework licenses are MIT and compatible with the repo license. | Option | Writing, search, i18n and versions | Theme and accessibility notes | License / package activity | 100-page static build | |---|---|---|---|---| | **Starlight / Astro**<br>[overview](https://starlight.astro.build/) · [Pagefind](https://starlight.astro.build/reference/configuration/#pagefind) · [authoring](https://starlight.astro.build/guides/authoring-content/) · [i18n](https://starlight.astro.build/guides/i18n/) · [theming](https://starlight.astro.build/guides/css-and-tailwind/) · [license](https://github.com/withastro/starlight/blob/main/LICENSE) · [verified package version](https://www.npmjs.com/package/@astrojs/starlight/v/0.42.4)<br>Screens: [390 light](https://git.kayg.org/attachments/363d2bbd-c345-445f-8c25-abb7fb56c0d9), [390 dark](https://git.kayg.org/attachments/9dbe489a-4cb5-4553-bebe-5e829d3052a9), [1440 light](https://git.kayg.org/attachments/b6559c5e-c14e-48a4-bdfc-97ccb8e862ec), [1440 dark](https://git.kayg.org/attachments/3bb0d25b-622c-4609-98e8-07679a88c68f) | Markdown, MDX, Markdoc; built-in Pagefind local search. i18n built in; no first-party version selector. | Responsive docs theme; built-in light/dark. CSS and component overrides; directly importing calternal tokens works. Skip link and keyboard search; screen-reader/reduced-motion behavior still needs an explicit pass. | MIT; `@astrojs/starlight` 0.42.4 (registry modified 2026-09-24). | 7.72 s / 4,448,529 B | | **VitePress / Vue + Vite**<br>[overview](https://vitepress.dev/guide/what-is-vitepress) · [local search](https://vitepress.dev/reference/default-theme-search) · [i18n](https://vitepress.dev/guide/i18n) · [theme config](https://vitepress.dev/reference/site-config) · [license](https://github.com/vuejs/vitepress/blob/main/LICENSE) · [verified package version](https://www.npmjs.com/package/vitepress/v/1.6.4)<br>Screens: [390 light](https://git.kayg.org/attachments/54784c0f-1775-4f27-8f93-b5549b163e67), [390 dark](https://git.kayg.org/attachments/c266524f-1f07-46a8-817a-8bdd6f2243aa), [1440 light](https://git.kayg.org/attachments/aa57e972-b58d-48fa-8b85-52b500ff1007), [1440 dark](https://git.kayg.org/attachments/4fe95160-a997-4208-ae53-429d264bf23d) | Markdown with Vue components; local MiniSearch. i18n built in; versions need a custom route/build arrangement. | Default docs theme has light/dark; theme CSS and Vue components accept tokens. Search dialog has keyboard interaction; screen-reader/reduced-motion audit still required. | MIT; 1.6.4 (2026-09-04). | 13.46 s / 6,332,649 B | | **Docusaurus / React**<br>[docs](https://docusaurus.io/docs) · [search](https://docusaurus.io/docs/search) · [versioning](https://docusaurus.io/docs/versioning) · [i18n](https://docusaurus.io/docs/i18n/introduction) · [license](https://github.com/facebook/docusaurus/blob/main/LICENSE) · [verified package version](https://www.npmjs.com/package/@docusaurus/core/v/3.10.2)<br>Screens: [390 light](https://git.kayg.org/attachments/8a6561dd-89fe-44db-a957-8d2c71a30a3b), [390 dark](https://git.kayg.org/attachments/81d8b84e-86ca-4ea2-aad7-092bd216e801), [1440 light](https://git.kayg.org/attachments/d75f7f6c-9743-4ac8-81be-60d2d4cd3050), [1440 dark](https://git.kayg.org/attachments/b952c2c5-beda-4745-aae0-cc9ba6223d3b) | Markdown/MDX; first-party versioning and i18n. Offline search requires a community plugin; Algolia is the first-party documented provider. | Dark mode and theme swizzling/CSS allow token mapping. Search is keyboard driven; verify AT and reduced motion in the selected theme. | MIT; 3.10.2 (2026-09-25). | 58.37 s / 4,734,046 B | | **Fumadocs / Next.js**<br>[static deploy](https://www.fumadocs.dev/docs/deploying/static) · [FlexSearch](https://www.fumadocs.dev/docs/headless/search/flexsearch) · [layouts](https://www.fumadocs.dev/docs/ui/layouts) · [search](https://www.fumadocs.dev/docs/search) · [license](https://github.com/fuma-nama/fumadocs/blob/dev/LICENSE) · [verified package version](https://www.npmjs.com/package/fumadocs-core/v/16.15.15)<br>Screens: [390 light](https://git.kayg.org/attachments/96dd3ff3-a6e3-4683-927a-99671cea2498), [390 dark](https://git.kayg.org/attachments/36c6e0df-d1d4-4108-b1d7-4771145aa8c7), [1440 light](https://git.kayg.org/attachments/f9489053-4008-44cf-8161-dc712ebc4a7b), [1440 dark](https://git.kayg.org/attachments/aeb2b14f-01d5-4e0b-811d-30501bb70f83) | MDX; FlexSearch static mode for offline search; i18n is available. Version selection is an application-level content/routing choice. | Docs, glass and other layouts are provided; React/Tailwind/CSS make token mapping flexible. Dark theme support; test final keyboard/AT behavior. | MIT; `fumadocs-core`/`fumadocs-ui` 16.15.15 (2026-09-27). | 55.31 s / 22,400,389 B | | **Nextra / Next.js**<br>[search](https://nextra.site/docs/guide/search) · [static export](https://nextra.site/docs/guide/static-exports) · [license](https://github.com/shuding/nextra/blob/main/LICENSE) · [verified package version](https://www.npmjs.com/package/nextra/v/4.6.1)<br>Screens: [390 light](https://git.kayg.org/attachments/cd40678a-7d31-4ab4-84d8-b1965d2b3b57), [390 dark](https://git.kayg.org/attachments/af34a229-d59d-4c38-aef5-933f23668aa2), [1440 light](https://git.kayg.org/attachments/5a17ff32-d1ff-44d7-8232-9d05c5c3e58f), [1440 dark](https://git.kayg.org/attachments/2bd4d8d4-1db9-48b5-b426-662500732c7f) | MDX; Pagefind can be added for local static search. Locale routes use Next.js; version navigation is custom. | Docs theme and dark mode are supplied; CSS/React overrides allow token mapping. Keyboard, AT and reduced motion need an explicit pass. | MIT; 4.6.1 (2025-12-04). | 145.91 s; static export failed, so no valid output size. | | **Rspress / Rsbuild**<br>[overview](https://www.rspress.dev/guide/start/introduction) · [multi-version](https://www.rspress.dev/guide/basic/multi-version) · [license](https://github.com/web-infra-dev/rspress/blob/main/LICENSE) · [verified package version](https://www.npmjs.com/package/@rspress/core/v/2.0.23)<br>Screens: [390 light](https://git.kayg.org/attachments/e39d896b-e879-4027-90a5-22c8ea91f2f6), [390 dark](https://git.kayg.org/attachments/b3a5b0af-55d3-4be7-8817-593d11ff905e), [1440 light](https://git.kayg.org/attachments/8e79b4dc-4e7c-48d9-8cb4-bd0acc0adee4), [1440 dark](https://git.kayg.org/attachments/8570273f-5859-4428-b479-3b7ca3d952e9) | MDX; built-in offline FlexSearch, i18n and multi-version docs. | Default docs theme supports light/dark; CSS and theme component overrides accept tokens. Verify AT and reduced motion in the chosen theme. | MIT; 2.0.23 (2026-09-29). | 7.58 s / 4,870,886 B | | **SvelteKit + mdsvex**<br>[Svelte packages](https://svelte.dev/packages) · [adapter-static](https://svelte.dev/docs/kit/adapter-static) · [mdsvex](https://mdsvex.pngwn.io/) · [license](https://github.com/sveltejs/kit/blob/main/LICENSE) · [verified package version](https://www.npmjs.com/package/@sveltejs/kit/v/2.70.3)<br>Screens: [390 light](https://git.kayg.org/attachments/a63bf744-4cb6-4d20-8616-4d6e9c83ac66), [390 dark](https://git.kayg.org/attachments/9fddfcdb-95b6-4681-a0c9-f2bd07a49de5), [1440 light](https://git.kayg.org/attachments/8ad9dc75-302f-4774-89d2-264dfcb3f033), [1440 dark](https://git.kayg.org/attachments/43dcfc12-dc3e-4d15-b56a-0d6d0d9bb9a6) | Markdown with Svelte via mdsvex; Pagefind was added for offline search. i18n, versions and docs UI are custom work. | Full control over tokens and motion, but no docs theme; build keyboard, screen-reader and dark-mode behavior as product UI. | MIT; SvelteKit 2.70.3, mdsvex 0.12.8, adapter-static 3.0.10. | 7.24 s / 1,235,061 B (bare shell, not a full docs theme). | **Benchmark method and limits.** One local run per option with the same generated 100-page corpus. Install time is excluded. Build time is wall time; output is uncompressed bytes from `du -sb`, including static search assets. These are single-run numbers on a shared host, not medians. Nextra’s test setup failed to produce a static export after 145.91 s, so it has no comparable size. The SvelteKit number is only a bare mdsvex shell plus Pagefind, without a complete documentation theme, so its output is not like-for-like. **Accessibility evidence.** Framework docs do not certify a full screen-reader or reduced-motion experience. The Starlight production build has a skip link and keyboard-opened search. Browser verification confirmed the skip link is the first Tab stop and the reduced-motion media query is active. I did not run a screen reader. The chosen theme still needs an explicit screen-reader and reduced-motion review. **Screenshots of the built site.** Captured from the production static build; each link is one page/viewport/theme. The browser pass covered all 4 pages at all widths and both themes. Search on the production preview returned the File over app page from the local Pagefind index. - **Home:** [390 light](https://git.kayg.org/attachments/68ec26e5-a180-46e5-bd5c-0c82b130397a), [390 dark](https://git.kayg.org/attachments/c8ffe220-3d1e-485f-9ef7-9f280f548d74), [820 light](https://git.kayg.org/attachments/11e7ff96-3817-4623-abcb-676e82165467), [820 dark](https://git.kayg.org/attachments/25b723fc-4668-42c4-bc5f-fd580827d166), [1440 light](https://git.kayg.org/attachments/808d8e5f-bbe5-45eb-9617-b7c3ce95c44a), [1440 dark](https://git.kayg.org/attachments/c29ceeee-b290-46bc-a5be-2cec9d769cdd) - **Tag grammar:** [390 light](https://git.kayg.org/attachments/aa01837d-930e-42ee-a4f9-a6c668ad7bbf), [390 dark](https://git.kayg.org/attachments/7ea903b0-9cdd-4631-8c52-d57acedb51a6), [820 light](https://git.kayg.org/attachments/478bac7f-330d-407c-aa50-025a2483870f), [820 dark](https://git.kayg.org/attachments/d27cfcae-31ea-4503-87ae-b63f205a16fd), [1440 light](https://git.kayg.org/attachments/e342cb2b-2b4c-433d-9018-ae28b7eda02c), [1440 dark](https://git.kayg.org/attachments/53022e04-3001-42d5-83b0-1ce6c934ee61) - **File over app:** [390 light](https://git.kayg.org/attachments/ada93215-10ae-4862-9b2a-62ae8b72b8cd), [390 dark](https://git.kayg.org/attachments/7c4df4c3-02b6-40a7-94de-f432f6419dc4), [820 light](https://git.kayg.org/attachments/1ccfa624-7dc2-4834-a9a5-78d49c40095f), [820 dark](https://git.kayg.org/attachments/35a2244f-ad39-40f3-a473-bccad3f2d901), [1440 light](https://git.kayg.org/attachments/630c3f32-4daf-4cd2-b70c-ac176513c1bf), [1440 dark](https://git.kayg.org/attachments/44b82f00-2902-4abf-a041-6566e017a19e) - **Connect Apple clients:** [390 light](https://git.kayg.org/attachments/db1fcf27-cad8-4deb-9c52-5ae2f9312f0c), [390 dark](https://git.kayg.org/attachments/5ad2722e-1b6a-4049-8009-2c9039c62114), [820 light](https://git.kayg.org/attachments/f06acfa0-9fb4-46a6-8d19-2aaf01dc929b), [820 dark](https://git.kayg.org/attachments/8de1e95c-0fbd-4946-8948-730df8b0113b), [1440 light](https://git.kayg.org/attachments/7f8e1c86-8273-4ab7-8f40-87d449c67dca), [1440 dark](https://git.kayg.org/attachments/6537a195-857f-4425-84b5-63c208793239)
Author
Owner

Job complete: docs-site (#415)

Head: 63454de0c08ade8c646115176f8076fc5ebaf174 (job/docs-site). This includes the required single merge of dev. The branch has two job commits: 3526a76c adds the site; bddf2c5c removes generated build output from source control and ignores it. No push, deploy, DNS change, or further merge was made.

Built: recommended Starlight (Astro) after comparing Starlight, VitePress, Docusaurus, Fumadocs, Nextra, Rspress and SvelteKit. The framework comparison, package/license sources, 100-page build measurements and all 28 framework screenshots are in my earlier issue comment. I attached 24 screenshots of the production docs pages at 390, 820 and 1440 px in light and dark themes. The browser run covered all 4 pages, confirmed the calternal palette/fonts and first-Tab skip link, and found the File over app guide through local Pagefind search.

apps/docs/ now has a static site with local Pagefind search, CSS imports from packages/ui/src/tokens.css and themes.css, local font symlinks, calternal color/font/motion styling, and three real guides:

  • guides/tags: the decided tag grammar from #403.
  • guides/file-over-app: files, Derived data, Index and Security state from #341.
  • guides/apple-clients: records that CalDAV/WebDAV connections are not available in v0.0.1 and explains the decided future CalDAV behavior. It does not provide unsupported setup steps.

The root bun.lock is updated. bun run build produces a static apps/docs/dist/ with Pagefind assets; I removed build output and Astro’s generated cache after verification, as requested. Screenshot files remain attached to the issue and are not committed.

Gate output

bun run check (verbatim):

$ astro check
11:44:18 [content] Syncing content
11:44:18 [content] Synced content
11:44:18 [types] Generated 1.66s
11:44:18 [check] Getting diagnostics for Astro files in /home/kayg/Developer/calternal-wt/docs-site/apps/docs...
Result (4 files): 
- 0 errors
- 0 warnings
- 0 hints

bun run test (verbatim):

$ bun test
bun test v1.4.2 (744846f84)

tests/content.test.ts:
(pass) user guides > documents every decided tag prefix and escape [0.32ms]
(pass) user guides > keeps files, Derived data, and Security state distinct [0.06ms]
(pass) user guides > does not tell Users to connect to unavailable DAV services [0.12ms]

 3 pass
 0 fail
 11 expect() calls
Ran 3 tests across 1 file. [14.00ms]

bun run build exited 0. Relevant output: 11:44:36 [build] 5 page(s) built in 6.51s and [starlight:pagefind] Finished building search index in 92ms. Rust crate/API files were not changed for this issue, so Rust crate gates were not applicable. cargo clean output:

     Removed 1 file, 356B total

Known gaps

  • The first skeleton does not yet include the other planned user docs (Money Markdown, saved places, XMP sidecars, Apps API/CLI/MCP/WebMCP, self-hosting and admin).
  • DESIGN.md excludes live CalDAV/WebDAV in v0.0.1. Contacts/CardDAV support and Apple profile steps remain undecided or unsupported and are not described as available.
  • No screen-reader audit was run. Starlight’s skip link and keyboard search work; reduced-motion CSS is present and the browser verified the reduced-motion preference. A screen-reader review remains.
  • The successful build warns that unused alternative font URLs in the shared tokens CSS are not in the docs font directory. The three fonts used by this site load from shared local assets. Astro also reports astro:head-inject and empty i18n/404 collection warnings; these did not stop the static build.

Decisions not specified in DESIGN.md

  • I recommend Starlight because it gives this site a complete static docs UI and offline Pagefind search, and measured 7.72 s / 4,448,529 B for the 100-page corpus. Rspress was close and has built-in versioning; the initial docs have no versioned content requirement.
  • I reused token and theme CSS by importing the existing files and linked only the font files used by the docs. I used Starlight’s standard documentation navigation and mapped it to calternal tokens.
  • I documented Apple connections as unavailable until the documented protocol support ships. This follows DESIGN.md’s v0.0.1 scope.
## Job complete: docs-site (#415) **Head:** `63454de0c08ade8c646115176f8076fc5ebaf174` (`job/docs-site`). This includes the required single merge of `dev`. The branch has two job commits: `3526a76c` adds the site; `bddf2c5c` removes generated build output from source control and ignores it. No push, deploy, DNS change, or further merge was made. **Built:** recommended Starlight (Astro) after comparing Starlight, VitePress, Docusaurus, Fumadocs, Nextra, Rspress and SvelteKit. The framework comparison, package/license sources, 100-page build measurements and all 28 framework screenshots are in my earlier issue comment. I attached 24 screenshots of the production docs pages at 390, 820 and 1440 px in light and dark themes. The browser run covered all 4 pages, confirmed the calternal palette/fonts and first-Tab skip link, and found the File over app guide through local Pagefind search. `apps/docs/` now has a static site with local Pagefind search, CSS imports from `packages/ui/src/tokens.css` and `themes.css`, local font symlinks, calternal color/font/motion styling, and three real guides: - `guides/tags`: the decided tag grammar from #403. - `guides/file-over-app`: files, Derived data, Index and Security state from #341. - `guides/apple-clients`: records that CalDAV/WebDAV connections are not available in v0.0.1 and explains the decided future CalDAV behavior. It does not provide unsupported setup steps. The root `bun.lock` is updated. `bun run build` produces a static `apps/docs/dist/` with Pagefind assets; I removed build output and Astro’s generated cache after verification, as requested. Screenshot files remain attached to the issue and are not committed. ### Gate output `bun run check` (verbatim): ```text $ astro check 11:44:18 [content] Syncing content 11:44:18 [content] Synced content 11:44:18 [types] Generated 1.66s 11:44:18 [check] Getting diagnostics for Astro files in /home/kayg/Developer/calternal-wt/docs-site/apps/docs... Result (4 files): - 0 errors - 0 warnings - 0 hints ``` `bun run test` (verbatim): ```text $ bun test bun test v1.4.2 (744846f84) tests/content.test.ts: (pass) user guides > documents every decided tag prefix and escape [0.32ms] (pass) user guides > keeps files, Derived data, and Security state distinct [0.06ms] (pass) user guides > does not tell Users to connect to unavailable DAV services [0.12ms] 3 pass 0 fail 11 expect() calls Ran 3 tests across 1 file. [14.00ms] ``` `bun run build` exited 0. Relevant output: `11:44:36 [build] 5 page(s) built in 6.51s` and `[starlight:pagefind] Finished building search index in 92ms.` Rust crate/API files were not changed for this issue, so Rust crate gates were not applicable. `cargo clean` output: ```text Removed 1 file, 356B total ``` ### Known gaps - The first skeleton does not yet include the other planned user docs (Money Markdown, saved places, XMP sidecars, Apps API/CLI/MCP/WebMCP, self-hosting and admin). - DESIGN.md excludes live CalDAV/WebDAV in v0.0.1. Contacts/CardDAV support and Apple profile steps remain undecided or unsupported and are not described as available. - No screen-reader audit was run. Starlight’s skip link and keyboard search work; reduced-motion CSS is present and the browser verified the reduced-motion preference. A screen-reader review remains. - The successful build warns that unused alternative font URLs in the shared tokens CSS are not in the docs font directory. The three fonts used by this site load from shared local assets. Astro also reports `astro:head-inject` and empty i18n/404 collection warnings; these did not stop the static build. ### Decisions not specified in DESIGN.md - I recommend Starlight because it gives this site a complete static docs UI and offline Pagefind search, and measured 7.72 s / 4,448,529 B for the 100-page corpus. Rspress was close and has built-in versioning; the initial docs have no versioned content requirement. - I reused token and theme CSS by importing the existing files and linked only the font files used by the docs. I used Starlight’s standard documentation navigation and mapped it to calternal tokens. - I documented Apple connections as unavailable until the documented protocol support ships. This follows DESIGN.md’s v0.0.1 scope.
Author
Owner

Resuming #415 on branch job/docs-site from head 63454de0c08ade8c646115176f8076fc5ebaf174; current dev is 191b179baac3ef4f5bebfe07ce91c4b7a887ace2. I have read CLAUDE.md, CONTEXT.md, the v0.0.1 scope and deep-link sections of docs/DESIGN.md, and the issue. I will complete the accepted Starlight docs work, correct the Apple scope and guide, build the additional decided guides, fix the docs warnings, add hosting notes, then run the requested gates and screenshot review.

Resuming #415 on branch `job/docs-site` from head `63454de0c08ade8c646115176f8076fc5ebaf174`; current `dev` is `191b179baac3ef4f5bebfe07ce91c4b7a887ace2`. I have read `CLAUDE.md`, `CONTEXT.md`, the v0.0.1 scope and deep-link sections of `docs/DESIGN.md`, and the issue. I will complete the accepted Starlight docs work, correct the Apple scope and guide, build the additional decided guides, fix the docs warnings, add hosting notes, then run the requested gates and screenshot review.
Author
Owner

Finding: the current content and checks encode the old release scope. docs/DESIGN.md §13 still says Photos, Tasks, Calendar and DAV are not in v0.0.1, and apps/docs/tests/content.test.ts requires the Apple guide to call DAV unavailable. The current Settings → Apps → App Passwords UI has a CalDAV preset, iPhone/iPad QR profile flow, Mac profile download, manual CalDAV fields and a WebDAV Files URL. The user-requested source issues #323, #358, #393, #318 and #395 cover these shipped paths. #356 and #391 are still open, so I will label per-area calendars and Saved places as coming. A baseline bun run build also reproduced unresolved alternative-font URLs, an empty Starlight i18n collection warning and the missing docs 404 entry.

Finding: the current content and checks encode the old release scope. `docs/DESIGN.md` §13 still says Photos, Tasks, Calendar and DAV are not in v0.0.1, and `apps/docs/tests/content.test.ts` requires the Apple guide to call DAV unavailable. The current `Settings → Apps → App Passwords` UI has a CalDAV preset, iPhone/iPad QR profile flow, Mac profile download, manual CalDAV fields and a WebDAV Files URL. The user-requested source issues #323, #358, #393, #318 and #395 cover these shipped paths. #356 and #391 are still open, so I will label per-area calendars and Saved places as coming. A baseline `bun run build` also reproduced unresolved alternative-font URLs, an empty Starlight i18n collection warning and the missing docs 404 entry.
Author
Owner

Evidence from this worktree: apps/web/src/routes/settings/account/AppPasswordsGroup.svelte still hard-codes “The profile is unsigned” for iPhone/iPad and Mac setup, and tells Mac users to accept an unknown-author warning. apps/web/e2e/app-passwords.mjs asserts that text. The docs now follow #318 and the #415 request: production profiles are signed. The local server has no profile-signing configuration, so local UI screenshots will show the stale unsigned copy. I kept the app package out of this docs-site change; please track the UI copy and test separately.

Evidence from this worktree: `apps/web/src/routes/settings/account/AppPasswordsGroup.svelte` still hard-codes “The profile is unsigned” for iPhone/iPad and Mac setup, and tells Mac users to accept an unknown-author warning. `apps/web/e2e/app-passwords.mjs` asserts that text. The docs now follow #318 and the #415 request: production profiles are signed. The local server has no profile-signing configuration, so local UI screenshots will show the stale unsigned copy. I kept the app package out of this docs-site change; please track the UI copy and test separately.
Author
Owner

Built

  • Corrected the v0.0.1 scope in docs/DESIGN.md with shipped feature and issue references.
  • Rewrote Apple client guidance for App Passwords, signed profiles, manual CalDAV, sync scope, Finder WebDAV, and troubleshooting.
  • Added Apps and access, Saved places, Sidecars and hidden files, and Deep links guides. Saved places stays marked Coming while #391 is open.
  • Removed unused font URL warnings, added English 404 text and a real static 404.html, and fixed the Astro module directive warning.
  • Added static hosting preparation at deploy/docs/README.md. It makes no deployment or DNS change.
  • Added content checks for the guide requirements and the 404 route.

Screenshots attached

Docs production build: all 9 pages at 390, 820, and 1440 px in light and dark (54 screenshots).

Page 390 px 820 px 1440 px
404 page light · dark light · dark light · dark
Apple clients light · dark light · dark light · dark
Apps light · dark light · dark light · dark
Deep links light · dark light · dark light · dark
File over app light · dark light · dark light · dark
Home light · dark light · dark light · dark
Saved places light · dark light · dark light · dark
Sidecars and hidden files light · dark light · dark light · dark
Tags light · dark light · dark light · dark

App Passwords UI from the built web production bundle. Credentials and the one-use QR are masked:

Decisions

  • Used Starlight, as the accepted recommendation in the job prompt.
  • Kept the 404 page in Starlight content with draft: true; this emits /404.html without adding it to the guide route.
  • Kept the shared UI tokens and themes, and filtered the docs CSS to its three used font families.
  • Described both static hosting options. Money content remains out until #404 format approval.

Known gaps

  • #356 and #391 remain open; the docs mark per-area calendars and Saved places as Coming.
  • The checked-in App Passwords UI still says the Apple profile is unsigned and tells Mac users to accept an unknown-author warning. The docs follow the deployed signing described by #318. The local screenshot server has no profile-signing config, so its UI shows the stale warning. I reported this evidence in a separate comment and kept the app UI package out of this docs-site job.

Head and gates

Head: ff1e6a37489d (docs: describe static docs hosting options).

bun run check output:

Result (5 files):
- 0 errors
- 0 warnings
- 0 hints

bun run test output:

$ bun test
bun test v1.4.2 (744846f84)

tests/content.test.ts:
(pass) user guides > documents every decided tag prefix and escape [1.77ms]
(pass) user guides > keeps files, Derived data, and Security state distinct [0.32ms]
(pass) user guides > documents the shipped Apple and WebDAV setup [0.34ms]
(pass) user guides > documents the defaults and controls for each client surface [0.22ms]
(pass) user guides > marks Saved places as coming while issue 391 is open [0.09ms]
(pass) user guides > documents Sidecar names and the hidden-name rule [0.05ms]
(pass) user guides > documents Copy link with stable URL identities [0.05ms]
(pass) user guides > provides a real static 404 page with a path home [0.05ms]

 8 pass
 0 fail
 41 expect() calls
Ran 8 tests across 1 file. [25.00ms]

bun run build output:

$ astro build
13:04:31 [content] Syncing content
13:04:31 [content] Synced content
13:04:31 [types] Generated 4.34s
13:04:31 [build] output: "static"
13:04:31 [build] mode: "static"
13:04:31 [build] directory: /home/kayg/Developer/calternal-wt/docs-site/apps/docs/dist/
13:04:31 [build] Collecting build info...
13:04:31 [build] ✓ Completed in 5.11s.
13:04:32 [build] Building static entrypoints...
13:04:36 [vite] ✓ built in 4.35s
13:04:36 [vite] ✓ built in 278ms
13:04:36 [build] Rearranging server assets...

 generating static routes 
13:04:36   ├─ /404.html (+73ms)
13:04:36   ├─ /guides/apple-clients/index.html (+16ms)
13:04:36   ├─ /guides/apps/index.html (+7ms)
13:04:36   ├─ /guides/deep-links/index.html (+7ms)
13:04:36   ├─ /guides/file-over-app/index.html (+6ms)
13:04:36   ├─ /guides/places/index.html (+9ms)
13:04:36   ├─ /guides/sidecars-hidden-files/index.html (+7ms)
13:04:36   ├─ /guides/tags/index.html (+17ms)
13:04:36   ├─ /index.html (+13ms)
13:04:37 ✓ Completed in 359ms.

13:04:37 [build] ✓ Completed in 5.13s.
13:04:37 [starlight:pagefind] Building search index with Pagefind...
13:04:37 [starlight:pagefind] Found 9 HTML files.
13:04:37 [starlight:pagefind] Finished building search index in 216ms.
13:04:37 [@astrojs/sitemap] `sitemap-index.xml` created at `dist`
13:04:37 [build] 9 page(s) built in 10.56s
13:04:37 [build] Complete!

cargo clean output:

     Removed 1 file, 356B total

No Rust crate changed, so Rust crate gates were not run. Generated apps/web/build and apps/docs/dist output was deleted after screenshots and gates.

## Built - Corrected the v0.0.1 scope in `docs/DESIGN.md` with shipped feature and issue references. - Rewrote Apple client guidance for App Passwords, signed profiles, manual CalDAV, sync scope, Finder WebDAV, and troubleshooting. - Added Apps and access, Saved places, Sidecars and hidden files, and Deep links guides. Saved places stays marked Coming while #391 is open. - Removed unused font URL warnings, added English 404 text and a real static `404.html`, and fixed the Astro module directive warning. - Added static hosting preparation at `deploy/docs/README.md`. It makes no deployment or DNS change. - Added content checks for the guide requirements and the 404 route. ## Screenshots attached Docs production build: all 9 pages at 390, 820, and 1440 px in light and dark (54 screenshots). | Page | 390 px | 820 px | 1440 px | | --- | --- | --- | --- | | 404 page | [light](https://git.kayg.org/attachments/c92440f1-7b7c-4f29-8d63-63fae4b18c83) · [dark](https://git.kayg.org/attachments/26208589-01ca-4d32-8453-86a335b5c969) | [light](https://git.kayg.org/attachments/48e71a05-53fa-45ab-8a53-5e2f996979a7) · [dark](https://git.kayg.org/attachments/dfa3992c-00d0-44f2-aeb9-67f4775bfc88) | [light](https://git.kayg.org/attachments/568e1730-29be-4815-83c1-6855adb65c86) · [dark](https://git.kayg.org/attachments/123a7db6-0edc-4a64-a709-dc1dd3d01dc7) | | Apple clients | [light](https://git.kayg.org/attachments/bd2c7104-c67e-4af4-badc-e639cf9241fe) · [dark](https://git.kayg.org/attachments/0a62bf92-b0e2-44f6-aba9-acac5f0e79e8) | [light](https://git.kayg.org/attachments/57f6be35-d4f2-4d3c-9e90-9499756ad1d3) · [dark](https://git.kayg.org/attachments/7565791f-ca44-4dff-b59f-2bfb7831c26f) | [light](https://git.kayg.org/attachments/c5ea557d-7738-4a64-9aef-302e45f45574) · [dark](https://git.kayg.org/attachments/c2eb8b9d-7ff3-46a4-9c14-e164f2e90fa2) | | Apps | [light](https://git.kayg.org/attachments/68a7b241-d1ca-48c1-965c-187ea7c32f89) · [dark](https://git.kayg.org/attachments/913ec6df-2f3f-4a14-a471-fb4bb9f39c5c) | [light](https://git.kayg.org/attachments/ed657163-6e1d-4ed7-9e32-fad19045ae09) · [dark](https://git.kayg.org/attachments/e0b847ad-04be-46c3-8b70-09c91888943b) | [light](https://git.kayg.org/attachments/65677257-4623-4e16-89af-5668728636ac) · [dark](https://git.kayg.org/attachments/cd1fd4cb-c038-4ba8-88a6-b05da4212eac) | | Deep links | [light](https://git.kayg.org/attachments/d710408d-d287-4066-a5c1-8ff1056d16da) · [dark](https://git.kayg.org/attachments/10a78f33-6f5c-4395-b8d6-b82e18012849) | [light](https://git.kayg.org/attachments/30bb966c-ff4a-4227-a011-174ab8bad1de) · [dark](https://git.kayg.org/attachments/e3a93cf6-c486-474c-b26c-d340fee06018) | [light](https://git.kayg.org/attachments/d9bd1fcb-208d-4405-9390-1fa7b675c70e) · [dark](https://git.kayg.org/attachments/dae1ba5b-83af-43dc-99c5-f4faeb9c2358) | | File over app | [light](https://git.kayg.org/attachments/6e2075ee-2bc8-4e11-955e-91e222480b8c) · [dark](https://git.kayg.org/attachments/213c8a6a-bb42-4f27-96c7-71d9ea90c4b8) | [light](https://git.kayg.org/attachments/a2b66b4c-370e-406d-b4f0-365a538ad156) · [dark](https://git.kayg.org/attachments/9877e37a-e06b-4c19-8bdf-2282a864447b) | [light](https://git.kayg.org/attachments/3959181f-cfc0-499c-9baa-1972c35b718f) · [dark](https://git.kayg.org/attachments/426592ce-b892-401a-bac1-52aa0e35f2de) | | Home | [light](https://git.kayg.org/attachments/2c6d3098-f25f-4a3b-9882-54b32bf9f25c) · [dark](https://git.kayg.org/attachments/d44f302d-5a0c-4ed6-8c05-b704e0cf3823) | [light](https://git.kayg.org/attachments/a6904871-549e-4524-9f65-976e4bfbac84) · [dark](https://git.kayg.org/attachments/8cf5df4e-a3bf-40c2-a3ff-38886fa38760) | [light](https://git.kayg.org/attachments/8b7c5bc5-d323-4be2-b125-1f5e701af78b) · [dark](https://git.kayg.org/attachments/c3b90bee-0c4a-40b4-b3b6-da128e1870dd) | | Saved places | [light](https://git.kayg.org/attachments/02796504-9bbf-4478-a751-9038f723374e) · [dark](https://git.kayg.org/attachments/9de9bf48-54de-4660-ae6c-317e68243088) | [light](https://git.kayg.org/attachments/92308a45-95ce-42f1-bc53-958d548e5dab) · [dark](https://git.kayg.org/attachments/64b29bc4-8fe9-40bd-a9a7-67baff18bfe6) | [light](https://git.kayg.org/attachments/7afab6e6-e4a1-4b3e-9906-b16f3740ff69) · [dark](https://git.kayg.org/attachments/1785f4cb-492c-4b5f-9b24-f5139fa59399) | | Sidecars and hidden files | [light](https://git.kayg.org/attachments/c4eb48f7-e374-4870-b644-ba65483dd24a) · [dark](https://git.kayg.org/attachments/f2baaa81-69a9-4d52-bf8f-d498ef54fea2) | [light](https://git.kayg.org/attachments/c4f6ac57-9357-4d29-a0ce-15970f2fb4a9) · [dark](https://git.kayg.org/attachments/d9356c32-cb27-4fe0-bda5-af8e259e288c) | [light](https://git.kayg.org/attachments/4197e142-5b13-4792-8da8-a90c22e6afa3) · [dark](https://git.kayg.org/attachments/52037863-72a8-4756-ac99-5d36dc91c756) | | Tags | [light](https://git.kayg.org/attachments/27af68cd-b0d3-4c17-b1f6-a32bb4eaacd8) · [dark](https://git.kayg.org/attachments/a1dee88b-5ef1-47e6-9d8a-7598940a2bc2) | [light](https://git.kayg.org/attachments/8f1826c2-5413-4f98-8a51-3a2b8d7c4969) · [dark](https://git.kayg.org/attachments/8852d617-0458-4008-bcba-2cf62c85683c) | [light](https://git.kayg.org/attachments/54816d73-7cf7-4c4f-94b9-cf21a93a63f7) · [dark](https://git.kayg.org/attachments/cea3d28c-8468-4276-bc61-06f627d96f0a) | App Passwords UI from the built web production bundle. Credentials and the one-use QR are masked: - [App Passwords page](https://git.kayg.org/attachments/45fbf0cd-f191-442f-b012-3303d7003920) - [Create Calendar App Password](https://git.kayg.org/attachments/f5b2fdff-d640-42ac-ac07-657988340804) - [Apple profile and manual setup, desktop light](https://git.kayg.org/attachments/9566bee7-3103-4f73-98dd-4ff2f03bf85d) - [Apple profile and manual setup, phone width](https://git.kayg.org/attachments/11e3cd7c-1dd7-4e89-bb6e-31e6494a0476) - [Apple profile and manual setup, desktop dark](https://git.kayg.org/attachments/132f5a68-6e20-4996-a91d-3cdce7044847) - [WebDAV App Password form](https://git.kayg.org/attachments/31adab1d-6500-4a33-8cbe-8691ae25f919) - [WebDAV credentials panel](https://git.kayg.org/attachments/5792fd13-7b7b-45d1-b150-d397a967e6f7) ## Decisions - Used Starlight, as the accepted recommendation in the job prompt. - Kept the 404 page in Starlight content with `draft: true`; this emits `/404.html` without adding it to the guide route. - Kept the shared UI tokens and themes, and filtered the docs CSS to its three used font families. - Described both static hosting options. Money content remains out until #404 format approval. ## Known gaps - #356 and #391 remain open; the docs mark per-area calendars and Saved places as Coming. - The checked-in App Passwords UI still says the Apple profile is unsigned and tells Mac users to accept an unknown-author warning. The docs follow the deployed signing described by #318. The local screenshot server has no profile-signing config, so its UI shows the stale warning. I reported this evidence in a separate comment and kept the app UI package out of this docs-site job. ## Head and gates Head: `ff1e6a37489d` (`docs: describe static docs hosting options`). `bun run check` output: ```text Result (5 files): - 0 errors - 0 warnings - 0 hints ``` `bun run test` output: ```text $ bun test bun test v1.4.2 (744846f84) tests/content.test.ts: (pass) user guides > documents every decided tag prefix and escape [1.77ms] (pass) user guides > keeps files, Derived data, and Security state distinct [0.32ms] (pass) user guides > documents the shipped Apple and WebDAV setup [0.34ms] (pass) user guides > documents the defaults and controls for each client surface [0.22ms] (pass) user guides > marks Saved places as coming while issue 391 is open [0.09ms] (pass) user guides > documents Sidecar names and the hidden-name rule [0.05ms] (pass) user guides > documents Copy link with stable URL identities [0.05ms] (pass) user guides > provides a real static 404 page with a path home [0.05ms] 8 pass 0 fail 41 expect() calls Ran 8 tests across 1 file. [25.00ms] ``` `bun run build` output: ```text $ astro build 13:04:31 [content] Syncing content 13:04:31 [content] Synced content 13:04:31 [types] Generated 4.34s 13:04:31 [build] output: "static" 13:04:31 [build] mode: "static" 13:04:31 [build] directory: /home/kayg/Developer/calternal-wt/docs-site/apps/docs/dist/ 13:04:31 [build] Collecting build info... 13:04:31 [build] ✓ Completed in 5.11s. 13:04:32 [build] Building static entrypoints... 13:04:36 [vite] ✓ built in 4.35s 13:04:36 [vite] ✓ built in 278ms 13:04:36 [build] Rearranging server assets... generating static routes 13:04:36 ├─ /404.html (+73ms) 13:04:36 ├─ /guides/apple-clients/index.html (+16ms) 13:04:36 ├─ /guides/apps/index.html (+7ms) 13:04:36 ├─ /guides/deep-links/index.html (+7ms) 13:04:36 ├─ /guides/file-over-app/index.html (+6ms) 13:04:36 ├─ /guides/places/index.html (+9ms) 13:04:36 ├─ /guides/sidecars-hidden-files/index.html (+7ms) 13:04:36 ├─ /guides/tags/index.html (+17ms) 13:04:36 ├─ /index.html (+13ms) 13:04:37 ✓ Completed in 359ms. 13:04:37 [build] ✓ Completed in 5.13s. 13:04:37 [starlight:pagefind] Building search index with Pagefind... 13:04:37 [starlight:pagefind] Found 9 HTML files. 13:04:37 [starlight:pagefind] Finished building search index in 216ms. 13:04:37 [@astrojs/sitemap] `sitemap-index.xml` created at `dist` 13:04:37 [build] 9 page(s) built in 10.56s 13:04:37 [build] Complete! ``` `cargo clean` output: ```text Removed 1 file, 356B total ``` No Rust crate changed, so Rust crate gates were not run. Generated `apps/web/build` and `apps/docs/dist` output was deleted after screenshots and gates.
Author
Owner

Evidence from the worktree and #420: FilesBrowser.svelte exposes one current “Show hidden files” checkbox for dot-prefixed names. It does not expose the planned “Show sidecar files” and “Show dot files” settings. Issue #420 remains Open and lists those switches and sidecar transport through file operations as build work. The guide also claimed hidden items could not be reached by item link or search; the current design/code only confirms dot-name listing and share filtering. I am revising the guide to describe the live Files action and mark the #420 controls and transport rules as Coming.

Evidence from the worktree and #420: `FilesBrowser.svelte` exposes one current “Show hidden files” checkbox for dot-prefixed names. It does not expose the planned “Show sidecar files” and “Show dot files” settings. Issue #420 remains Open and lists those switches and sidecar transport through file operations as build work. The guide also claimed hidden items could not be reached by item link or search; the current design/code only confirms dot-name listing and share filtering. I am revising the guide to describe the live Files action and mark the #420 controls and transport rules as Coming.
Author
Owner

#415 final update

This update supersedes the earlier report head and replaces the six Sidecars and hidden files screenshots linked in the earlier 54-image matrix. The other 48 docs screenshots and 7 App Passwords UI screenshots remain attached in that comment.

What changed

  • Corrected docs/DESIGN.md v0.0.1 scope with shipped and deployed feature references.
  • Rewrote the Apple guide for App Passwords, signed profiles, manual CalDAV setup, sync scope, Finder WebDAV, and troubleshooting.
  • Added guides for Apps and access, Saved places, Sidecars and hidden files, and Deep links. Per-area calendars, Saved places, and the unmerged #420 controls stay marked Coming.
  • Fixed unused font URL and i18n/404 build warnings; added /404.html.
  • Added the static hosting note at deploy/docs/README.md; no deployment or DNS changes.
  • Added content tests for guide claims and the 404 page.

Files

  • docs/DESIGN.md, deploy/docs/README.md, bun.lock.
  • apps/docs/package.json, .gitignore, astro.config.mjs, tsconfig.json.
  • Docs: src/content/docs/guides/{apple-clients,apps,deep-links,file-over-app,places,sidecars-hidden-files,tags}.md, src/content/docs/{index,404}.md, src/content/i18n/en.json.
  • Site code and styles: src/content.config.ts, src/styles/docs.css, public/theme-sync.js, tests/content.test.ts, and six font files under public/fonts/.

Updated screenshots

These six production-build screenshots replace the earlier Sidecars and hidden files captures:

Head and decisions

Head: 830618cc3752 (docs: distinguish current and planned sidecar rules). The work is on job/docs-site; no push, deploy, or merge was done.

  • Used Starlight per the accepted recommendation in the job prompt.
  • Kept the 404 content as a Starlight draft route with explicit English i18n strings.
  • Kept shared UI tokens and themes, and imported only the docs-used font families: Google Sans, Bricolage Grotesque, and Maple Mono.
  • Described both allowed static-hosting options and left the choice open. Money content remains out pending #404 approval.
  • #420 is still open. The guide describes the live dot-file action and marks the separate switches and Sidecar transport rules as Coming.

Known gaps

  • The checked-in App Passwords UI still says Apple profiles are unsigned and asks Mac users to accept an unknown-author warning. The local screenshot server has no signing configuration. This evidence was reported in a prior #415 comment; app UI source was outside this docs-site change.
  • #356 and #391 remain open; per-area calendars and Saved places are marked Coming.

Gate output

bun run check:

$ astro check
13:17:35 [content] Syncing content
13:17:35 [content] Synced content
13:17:35 [types] Generated 3.64s
13:17:35 [check] Getting diagnostics for Astro files in /home/kayg/Developer/calternal-wt/docs-site/apps/docs...
Result (5 files):
- 0 errors
- 0 warnings
- 0 hints

bun run test:

$ bun test
bun test v1.4.2 (744846f84)

tests/content.test.ts:
(pass) user guides > documents every decided tag prefix and escape [0.45ms]
(pass) user guides > keeps files, Derived data, and Security state distinct [0.10ms]
(pass) user guides > documents the shipped Apple and WebDAV setup [0.13ms]
(pass) user guides > documents the defaults and controls for each client surface [0.08ms]
(pass) user guides > marks Saved places as coming while issue 391 is open [0.06ms]
(pass) user guides > separates current dot-file visibility from planned Sidecar controls [0.08ms]
(pass) user guides > documents Copy link with stable URL identities [0.05ms]
(pass) user guides > provides a real static 404 page with a path home [0.05ms]

 8 pass
 0 fail
 49 expect() calls
Ran 8 tests across 1 file. [21.00ms]

bun run build:

$ astro build
13:17:51 [content] Syncing content
13:17:51 [content] Synced content
13:17:51 [types] Generated 1.64s
13:17:51 [build] output: "static"
13:17:51 [build] mode: "static"
13:17:51 [build] directory: /home/kayg/Developer/calternal-wt/docs-site/apps/docs/dist/
13:17:51 [build] Collecting build info...
13:17:51 [build] ✓ Completed in 3.10s.
13:17:51 [build] Building static entrypoints...
13:17:53 [vite] ✓ built in 1.95s
13:17:53 [vite] ✓ built in 201ms
13:17:53 [build] Rearranging server assets...

 generating static routes 
13:17:53   ├─ /404.html (+39ms)
13:17:53   ├─ /guides/apple-clients/index.html (+16ms)
13:17:53   ├─ /guides/apps/index.html (+7ms)
13:17:53   ├─ /guides/deep-links/index.html (+6ms)
13:17:53   ├─ /guides/file-over-app/index.html (+6ms)
13:17:53   ├─ /guides/places/index.html (+7ms)
13:17:53   ├─ /guides/sidecars-hidden-files/index.html (+6ms)
13:17:53   ├─ /guides/tags/index.html (+10ms)
13:17:53   ├─ /index.html (+18ms)
13:17:53 ✓ Completed in 188ms.

13:17:53 [build] ✓ Completed in 2.42s.
13:17:53 [starlight:pagefind] Building search index with Pagefind...
13:17:53 [starlight:pagefind] Found 9 HTML files.
13:17:53 [starlight:pagefind] Finished building search index in 49ms.
13:17:53 [@astrojs/sitemap] `sitemap-index.xml` created at `dist`
13:17:53 [build] 9 page(s) built in 5.59s
13:17:53 [build] Complete!

cargo clean:

     Removed 0 files

No Rust crate changed, so Rust crate gates were not run. The docs and web build output was deleted after the screenshots and gates. Docs dependency versions were checked with bun info: Starlight 0.42.4, Astro 7.3.5, and @astrojs/check 0.9.10; all report MIT licenses.

#415 final update This update supersedes the earlier report head and replaces the six Sidecars and hidden files screenshots linked in the earlier 54-image matrix. The other 48 docs screenshots and 7 App Passwords UI screenshots remain attached in that comment. ## What changed - Corrected `docs/DESIGN.md` v0.0.1 scope with shipped and deployed feature references. - Rewrote the Apple guide for App Passwords, signed profiles, manual CalDAV setup, sync scope, Finder WebDAV, and troubleshooting. - Added guides for Apps and access, Saved places, Sidecars and hidden files, and Deep links. Per-area calendars, Saved places, and the unmerged #420 controls stay marked Coming. - Fixed unused font URL and i18n/404 build warnings; added `/404.html`. - Added the static hosting note at `deploy/docs/README.md`; no deployment or DNS changes. - Added content tests for guide claims and the 404 page. ## Files - `docs/DESIGN.md`, `deploy/docs/README.md`, `bun.lock`. - `apps/docs/package.json`, `.gitignore`, `astro.config.mjs`, `tsconfig.json`. - Docs: `src/content/docs/guides/{apple-clients,apps,deep-links,file-over-app,places,sidecars-hidden-files,tags}.md`, `src/content/docs/{index,404}.md`, `src/content/i18n/en.json`. - Site code and styles: `src/content.config.ts`, `src/styles/docs.css`, `public/theme-sync.js`, `tests/content.test.ts`, and six font files under `public/fonts/`. ## Updated screenshots These six production-build screenshots replace the earlier Sidecars and hidden files captures: - [390 light](https://git.kayg.org/attachments/66bb8167-9261-4892-babf-cf534ff39237) · [390 dark](https://git.kayg.org/attachments/d1dac9de-1103-4630-ab75-d7a204e60914) - [820 light](https://git.kayg.org/attachments/f8ee13da-cb26-4dfc-84be-e6c7c196cdfe) · [820 dark](https://git.kayg.org/attachments/c8ffd7b7-af7e-4b5c-a1cd-c71958788900) - [1440 light](https://git.kayg.org/attachments/47ff3c7a-db12-4770-93f7-ba780785c93a) · [1440 dark](https://git.kayg.org/attachments/bcc6ef44-02f6-47d1-bf3b-1257e8e86a04) ## Head and decisions Head: `830618cc3752` (`docs: distinguish current and planned sidecar rules`). The work is on `job/docs-site`; no push, deploy, or merge was done. - Used Starlight per the accepted recommendation in the job prompt. - Kept the 404 content as a Starlight draft route with explicit English i18n strings. - Kept shared UI tokens and themes, and imported only the docs-used font families: Google Sans, Bricolage Grotesque, and Maple Mono. - Described both allowed static-hosting options and left the choice open. Money content remains out pending #404 approval. - #420 is still open. The guide describes the live dot-file action and marks the separate switches and Sidecar transport rules as Coming. ## Known gaps - The checked-in App Passwords UI still says Apple profiles are unsigned and asks Mac users to accept an unknown-author warning. The local screenshot server has no signing configuration. This evidence was reported in a prior #415 comment; app UI source was outside this docs-site change. - #356 and #391 remain open; per-area calendars and Saved places are marked Coming. ## Gate output `bun run check`: ```text $ astro check 13:17:35 [content] Syncing content 13:17:35 [content] Synced content 13:17:35 [types] Generated 3.64s 13:17:35 [check] Getting diagnostics for Astro files in /home/kayg/Developer/calternal-wt/docs-site/apps/docs... Result (5 files): - 0 errors - 0 warnings - 0 hints ``` `bun run test`: ```text $ bun test bun test v1.4.2 (744846f84) tests/content.test.ts: (pass) user guides > documents every decided tag prefix and escape [0.45ms] (pass) user guides > keeps files, Derived data, and Security state distinct [0.10ms] (pass) user guides > documents the shipped Apple and WebDAV setup [0.13ms] (pass) user guides > documents the defaults and controls for each client surface [0.08ms] (pass) user guides > marks Saved places as coming while issue 391 is open [0.06ms] (pass) user guides > separates current dot-file visibility from planned Sidecar controls [0.08ms] (pass) user guides > documents Copy link with stable URL identities [0.05ms] (pass) user guides > provides a real static 404 page with a path home [0.05ms] 8 pass 0 fail 49 expect() calls Ran 8 tests across 1 file. [21.00ms] ``` `bun run build`: ```text $ astro build 13:17:51 [content] Syncing content 13:17:51 [content] Synced content 13:17:51 [types] Generated 1.64s 13:17:51 [build] output: "static" 13:17:51 [build] mode: "static" 13:17:51 [build] directory: /home/kayg/Developer/calternal-wt/docs-site/apps/docs/dist/ 13:17:51 [build] Collecting build info... 13:17:51 [build] ✓ Completed in 3.10s. 13:17:51 [build] Building static entrypoints... 13:17:53 [vite] ✓ built in 1.95s 13:17:53 [vite] ✓ built in 201ms 13:17:53 [build] Rearranging server assets... generating static routes 13:17:53 ├─ /404.html (+39ms) 13:17:53 ├─ /guides/apple-clients/index.html (+16ms) 13:17:53 ├─ /guides/apps/index.html (+7ms) 13:17:53 ├─ /guides/deep-links/index.html (+6ms) 13:17:53 ├─ /guides/file-over-app/index.html (+6ms) 13:17:53 ├─ /guides/places/index.html (+7ms) 13:17:53 ├─ /guides/sidecars-hidden-files/index.html (+6ms) 13:17:53 ├─ /guides/tags/index.html (+10ms) 13:17:53 ├─ /index.html (+18ms) 13:17:53 ✓ Completed in 188ms. 13:17:53 [build] ✓ Completed in 2.42s. 13:17:53 [starlight:pagefind] Building search index with Pagefind... 13:17:53 [starlight:pagefind] Found 9 HTML files. 13:17:53 [starlight:pagefind] Finished building search index in 49ms. 13:17:53 [@astrojs/sitemap] `sitemap-index.xml` created at `dist` 13:17:53 [build] 9 page(s) built in 5.59s 13:17:53 [build] Complete! ``` `cargo clean`: ```text Removed 0 files ``` No Rust crate changed, so Rust crate gates were not run. The docs and web build output was deleted after the screenshots and gates. Docs dependency versions were checked with `bun info`: Starlight 0.42.4, Astro 7.3.5, and @astrojs/check 0.9.10; all report MIT licenses.
Author
Owner

Merged into dev and pushed (43c1377c); orchestrator visual review passed. Deploy to calternal.cloud follows once the #356/#393 Apple GO/NO-GO clears.

Merged into dev and pushed (43c1377c); orchestrator visual review passed. Deploy to calternal.cloud follows once the #356/#393 Apple GO/NO-GO clears.
kayg closed this issue 2026-09-29 14:58:09 +00:00
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#415
No description provided.