pfsteve · Nov 6, 2026 · Nov 6, 2026 · Nov 6, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,52 @@
+name: docs
+# The public documentation site at docs.pushform.io. Runs only when the site changes: docs/ except the in-app help
+# guides in docs/help, which the site does not build from.
+on:
+  pull_request:
+    paths: ['docs/**', '!docs/help/**', '.github/workflows/docs.yml']
+  push:
+    branches: [main]
+    paths: ['docs/**', '!docs/help/**', '.github/workflows/docs.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  ASTRO_TELEMETRY_DISABLED: 1
+
+jobs:
+  build:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/setup
+      - run: pnpm docs:build
+
+  # Publishes to the Cloudflare Pages project pushform-docs. Needs the Production environment's
+  # CLOUDFLARE_API_TOKEN secret (Workers & Pages: Edit) and CLOUDFLARE_ACCOUNT_ID variable.
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    environment: Production
+    concurrency: { group: deploy-docs-production, cancel-in-progress: false }
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/setup
+      - run: pnpm docs:build
+      - uses: cloudflare/wrangler-action@v4
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy docs/dist --project-name pushform-docs --branch main --commit-hash ${{ github.sha }} --commit-dirty=false
+      - name: Verify the docs site serves this build
+        shell: bash
+        run: |
+          for attempt in 1 2 3 4 5 6; do
+            if node scripts/verify-static-deploy.mjs https://docs.pushform.io docs/dist; then
+              exit 0
+            fi
+            if [[ "$attempt" -lt 6 ]]; then sleep 10; fi
+          done
+          exit 1
diff --git a/README.md b/README.md
@@ -28,10 +28,12 @@ The app requires sign-in and stores documents in Supabase. Point `apps/web/.env.
 ```
 packages/   core geom kernel model inference commands render io ui mcp cloud testing
 apps/       web desktop commons
-docs/help/  user-facing help guides
+docs/       documentation site published at docs.pushform.io
+docs/help/  in-app help guides that AI Chat searches (not part of the site)
 ```
 
 The standalone Commons frontend has its own build and catalog configuration; see [apps/commons](apps/commons/README.md).
+The documentation site has its own build; see [docs](docs/README.md).
 
 ## License
 

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,3 @@
+# Astro's generated types and build output.
+.astro/
+dist/
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,24 @@
+# PushForm documentation site
+
+The public documentation at [docs.pushform.io](https://docs.pushform.io), built with [Astro Starlight](https://starlight.astro.build/).
+
+```sh
+pnpm docs:dev     # http://localhost:4321
+pnpm docs:build   # static site in docs/dist
+```
+
+## Pages
+
+Pages are Markdown or MDX files in `src/content/docs/`. A file's path is its URL: `src/content/docs/getting-started/first-model.md` is `/getting-started/first-model/`. Each page needs a `title` and a `description` in its front matter. Set `sidebar.order` to place it within its section.
+
+Add a new section by creating a folder and adding it to `sidebar` in `astro.config.mjs`.
+
+Write for people reading in a browser: explain the task and show the steps in order. Describe PushForm's own behavior, and check it against the app.
+
+## The in-app help is separate
+
+`help/` holds the guides AI Chat searches inside the app. They are written as short, self-contained task passages for retrieval, and the site does not build from them. When a change affects what users see, update both: the guide in `help/` and the matching page here.
+
+## Publishing
+
+The `docs` workflow runs only when something under `docs/` changes, apart from `docs/help/`. On a pull request it builds the site. On `main` it deploys `docs/dist` to the Cloudflare Pages project `pushform-docs` and checks that docs.pushform.io serves the new build. Run it by hand from the Actions tab to redeploy.
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 PushForm contributors
+// The public PushForm documentation site, published at docs.pushform.io.
+// Pages live in src/content/docs. The in-app help guides in ../docs/help are a separate source and are not built here.
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  site: 'https://docs.pushform.io',
+  trailingSlash: 'ignore',
+  integrations: [
+    starlight({
+      title: 'PushForm Docs',
+      description: 'Guides for PushForm, push/pull 2D and 3D modeling for woodworkers, carpenters, architects and landscapers.',
+      logo: { src: './src/assets/pf-logo-mark.svg', alt: 'PushForm' },
+      favicon: '/favicon.svg',
+      customCss: ['./src/styles/pushform.css'],
+      social: [
+        { icon: 'github', label: 'PushForm on GitHub', href: 'https://github.com/PushForm/pushform-app' },
+      ],
+      editLink: { baseUrl: 'https://github.com/PushForm/pushform-app/edit/main/docs/' },
+      sidebar: [
+        { label: 'Getting started', items: [{ autogenerate: { directory: 'getting-started' } }] },
+      ],
+    }),
+  ],
+});
diff --git a/docs/package.json b/docs/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "@pushform/docs",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "license": "GPL-3.0-or-later",
+  "scripts": {
+    "dev": "astro dev --port 4321",
+    "build": "astro build",
+    "preview": "astro preview --port 4321",
+    "check": "astro check"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.42.10",
+    "astro": "^7.4.7"
+  }
+}
diff --git a/docs/public/_headers b/docs/public/_headers
@@ -0,0 +1,9 @@
+/*
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: strict-origin-when-cross-origin
+  Permissions-Policy: camera=(), microphone=(), geolocation=()
+  Content-Security-Policy: frame-ancestors 'none'
+
+# Built JS and CSS carry a content hash in their names, so a browser can keep them without rechecking.
+/_astro/*
+  Cache-Control: public, max-age=31536000, immutable
diff --git a/docs/public/favicon.svg b/docs/public/favicon.svg
diff --git a/docs/src/assets/pf-logo-mark.svg b/docs/src/assets/pf-logo-mark.svg
diff --git a/docs/src/content.config.ts b/docs/src/content.config.ts
@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 PushForm contributors
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};
diff --git a/docs/src/content/docs/getting-started/find-your-way-around.md b/docs/src/content/docs/getting-started/find-your-way-around.md
@@ -0,0 +1,42 @@
+---
+title: Find your way around
+description: Command search, side panels, files and Undo.
+sidebar:
+  order: 3
+---
+
+## Find any command by name
+
+Press **Ctrl+K** (or **Cmd+K** on macOS) to jump to command search. Type part of a tool or action's name, choose a result with the arrow keys, and press **Enter**. **Escape** closes search without running anything.
+
+Search shows commands for the editor you're in, so a Layout drawing doesn't offer Modeling's Push/Pull.
+
+## Side panels
+
+The menu bar on the left opens these panels:
+
+- **Files**: browse your projects and open files without leaving your drawing.
+- **AI Chat**: ask how to do something. It can point out the control you need.
+- **Object browser**: see what's in your document and select it.
+
+Opening one panel replaces the one already showing. Drag the panel's right edge to resize it.
+
+## Files and projects
+
+Your documents are kept in projects in the cloud. In **Files**, choose a project, then open folders and files. A file that's already open switches to its tab, keeping any unsaved changes.
+
+Right-click a project, folder or file to **Rename** it, **Move** it or **Move to Trash**. To restore something from the trash, go Home and open **Trash**.
+
+## Undo and cancel
+
+| Action | Windows and Linux | macOS |
+| --- | --- | --- |
+| Undo | Ctrl+Z | Cmd+Z |
+| Redo | Ctrl+Shift+Z or Ctrl+Y | Cmd+Shift+Z |
+| Cancel the current tool step | Escape | Escape |
+
+Each document has its own Undo history.
+
+## Go home
+
+Click the PushForm logo to return Home. Your documents stay open, and **Continue working** takes you back to them.
diff --git a/docs/src/content/docs/getting-started/first-model.md b/docs/src/content/docs/getting-started/first-model.md
@@ -0,0 +1,34 @@
+---
+title: Your first model
+description: Draw a rectangle, push it into a solid and give it exact dimensions.
+sidebar:
+  order: 2
+---
+
+Most PushForm models start the same way: draw a flat shape, then push or pull it into a solid. This guide makes a simple board.
+
+Open a new **Model** document before you start.
+
+## Draw a rectangle
+
+1. In the Draw group of the toolbar, choose **Rectangle** from the Shape dropdown.
+2. Click once for the first corner.
+3. Before you click again, type the width, press **Tab**, type the height, then press **Enter**.
+
+You now have a flat rectangular face. Press **Escape** at any point to cancel an unfinished rectangle.
+
+## Push it into a solid
+
+1. Choose **Push/Pull**.
+2. Click the rectangle and move the pointer away from it. You'll see a preview of the solid.
+3. Type the thickness and press **Enter**, or click again to set it where the preview is.
+
+The face is now a solid board. Push/Pull on one of its faces later to make it longer, wider or thicker. On a solid, a negative distance pushes into it.
+
+## If something goes wrong
+
+- **Undo** with **Ctrl+Z** (or **Cmd+Z** on macOS).
+- A loose line can't be pushed. The boundary must be closed and flat so PushForm can fill it with a face.
+- PushForm keeps solids valid. If an operation can't produce a valid solid, it's rejected and nothing changes.
+
+Next: [find your way around](/getting-started/find-your-way-around/).
diff --git a/docs/src/content/docs/getting-started/get-help.md b/docs/src/content/docs/getting-started/get-help.md
@@ -0,0 +1,22 @@
+---
+title: Get help
+description: Ask AI Chat, report a problem or request a feature.
+sidebar:
+  order: 4
+---
+
+## Ask AI Chat
+
+Open **AI Chat** from the left menu bar in either editor, or with the chat button on Home. Ask what you want to do, for example "How do I draw an eight-sided polygon in Layout?"
+
+When it can, AI Chat highlights the control you need with a short glow. It won't click anything or change your document for you.
+
+## Report a problem or request a feature
+
+Tell AI Chat what you did and what happened, or describe the feature you'd like. Before it files anything, it shows a short summary for you to check and confirm.
+
+When you report a problem, it helps to include your version. Search for **About PushForm** with **Ctrl+K** (or **Cmd+K** on macOS) to see it.
+
+## Source code
+
+PushForm is open source under the GNU GPLv3. The code is on [GitHub](https://github.com/PushForm/pushform-app).
diff --git a/docs/src/content/docs/getting-started/open-pushform.md b/docs/src/content/docs/getting-started/open-pushform.md
@@ -0,0 +1,37 @@
+---
+title: Open PushForm
+description: Use PushForm in a browser or as a desktop app, and sign in.
+sidebar:
+  order: 1
+---
+
+PushForm runs in your browser or as a desktop app. Both use the same account and the same cloud files.
+
+## In your browser
+
+Go to [app.pushform.io](https://app.pushform.io). There's nothing to install.
+
+## On your desktop
+
+Download the installer for your platform from [pushform.io/download](https://pushform.io/download).
+
+On macOS, open the downloaded `.dmg` file and drag **PushForm** onto **Applications**. When copying finishes, eject the disk image and open PushForm from your Applications folder.
+
+When a desktop update is ready, a notice offers **Restart to update**. PushForm saves your open documents before it restarts. To check yourself, search for **Check for updates** with **Ctrl+K** (or **Cmd+K** on macOS).
+
+## Sign in
+
+Enter your email address and request a sign-in email. Then type the code from that email, or use its sign-in link if it has one. Codes are 6 to 10 digits long. If yours expires, request another.
+
+The first time you sign in, PushForm asks for your name, whether you're an individual or a company, and your industry. Accept the Terms of Use to continue.
+
+## Start a document
+
+PushForm has two editors:
+
+- **Modeling** for 3D work.
+- **Layout** for drawings on pages, with dimensions, text and tables.
+
+Choose the **+** button and pick **Model** or **Layout**. Each document gets its own tab and its own Undo history.
+
+Next: [build your first model](/getting-started/first-model/).
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -0,0 +1,34 @@
+---
+title: PushForm Docs
+description: Learn PushForm, push/pull 2D and 3D modeling for woodworkers, carpenters, architects and landscapers.
+template: splash
+hero:
+  tagline: Model it in 3D, then draw it up on pages. Guides for both editors.
+  image:
+    file: ../../assets/pf-logo-mark.svg
+  actions:
+    - text: Get started
+      link: /getting-started/open-pushform/
+      icon: right-arrow
+    - text: Open PushForm
+      link: https://app.pushform.io
+      icon: external
+      variant: minimal
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+<CardGrid>
+  <Card title="Open PushForm" icon="rocket">
+    Use PushForm in your browser or install the desktop app, then sign in. [Open PushForm](/getting-started/open-pushform/)
+  </Card>
+  <Card title="Your first model" icon="pencil">
+    Draw a rectangle and push it into a solid, with exact sizes. [Build a first model](/getting-started/first-model/)
+  </Card>
+  <Card title="Find your way around" icon="magnifier">
+    Command search, side panels, files and Undo. [Find your way around](/getting-started/find-your-way-around/)
+  </Card>
+  <Card title="Get help" icon="comment">
+    Ask AI Chat, report a problem or request a feature. [Get help](/getting-started/get-help/)
+  </Card>
+</CardGrid>
diff --git a/docs/src/styles/pushform.css b/docs/src/styles/pushform.css
@@ -0,0 +1,14 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later
+ * Copyright 2026 PushForm contributors */
+/* PushForm brand accent on Starlight's default theme. */
+:root {
+  --sl-color-accent-low: #0c2a4d;
+  --sl-color-accent: #247ae0;
+  --sl-color-accent-high: #b9d6f8;
+}
+
+:root[data-theme='light'] {
+  --sl-color-accent-low: #d6e7fb;
+  --sl-color-accent: #1a63bd;
+  --sl-color-accent-high: #0c2a4d;
+}
diff --git a/docs/tsconfig.json b/docs/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist", "help"]
+}
diff --git a/eslint.config.js b/eslint.config.js
@@ -4,7 +4,7 @@ import js from '@eslint/js';
 import tseslint from 'typescript-eslint';
 
 export default tseslint.config(
-  { ignores: ['**/dist/**', '**/node_modules/**', 'apps/desktop/src-tauri/**', '**/*.d.ts', '.claude/worktrees/**'] },
+  { ignores: ['**/dist/**', '**/node_modules/**', 'apps/desktop/src-tauri/**', '**/*.d.ts', '.claude/worktrees/**', '**/.astro/**'] },
   js.configs.recommended,
   ...tseslint.configs.recommended,
   {