beta 49 updates and package with claude section

MattDHill · MattDHill · commit 589ceda91931 · 2026-02-19T20:25:11.000-07:00
diff --git a/build.sh b/build.sh
@@ -17,6 +17,15 @@ mkdir -p docs
 (cd packaging && MDBOOK_OUTPUT__HTML__SITE_URL="/packaging/$PACKAGING_VERSION/" \
   mdbook build -d "../docs/packaging/$PACKAGING_VERSION")
 
+# Redirect stubs: /book/ → /book/version/
+for pair in "start-os:$START_OS_VERSION" "start-tunnel:$START_TUNNEL_VERSION" "packaging:$PACKAGING_VERSION"; do
+  book="${pair%%:*}"
+  version="${pair##*:}"
+  cat > "docs/$book/index.html" <<EOF
+<!doctype html><meta http-equiv="refresh" content="0; url=/$book/$version/">
+EOF
+done
+
 # Landing page
 cp landing/index.html docs/index.html
 
diff --git a/landing/index.html b/landing/index.html
@@ -48,11 +48,10 @@
       }
 
       .cards {
-        display: flex;
+        display: grid;
+        grid-template-columns: repeat(2, 300px);
         gap: 2rem;
-        flex-wrap: wrap;
         justify-content: center;
-        max-width: 700px;
       }
 
       a.card {
@@ -108,13 +107,20 @@ <h1>Start9 Docs</h1>
 
     <div class="cards">
       <a class="card" href="/start-os/">
-        <h2>StartOS</h2>
+        <h2>StartOS v0.4.0</h2>
         <p>
           A server operating system optimized for self-hosting services on a
           personal server.
         </p>
       </a>
 
+      <a class="card" href="/0.3.5.x/">
+        <h2>StartOS v0.3.5.1</h2>
+        <p>
+          Documentation for StartOS version 0.3.5.1 and earlier.
+        </p>
+      </a>
+
       <a class="card" href="/start-tunnel/">
         <h2>StartTunnel</h2>
         <p>
diff --git a/packaging/src/SAMPLE-CLAUDE.txt b/packaging/src/SAMPLE-CLAUDE.txt
@@ -0,0 +1,28 @@
+# StartOS Service Packager
+
+You are a StartOS service packager. You help create, maintain, and update `.s9pk` service packages for StartOS.
+
+## Packaging Guide
+
+The packaging guide is your primary reference. Follow it exactly. Read `SUMMARY.md` first to identify which sections are relevant to the current task, then read only those `.md` files directly. Do not load all sections at once.
+
+### Local Read (preferred)
+
+If `start-docs/packaging/src/` exists in the workspace, use the Read tool:
+
+```
+start-docs/packaging/src/SUMMARY.md       # Read first — section index
+start-docs/packaging/src/<section>.md      # Then read only what you need
+```
+
+### Web Fetch (fallback)
+
+If the local docs are not available, use WebFetch:
+
+```
+WebFetch: https://docs.start9.com/packaging/llms.txt    # Fetch first — section index
+WebFetch: https://docs.start9.com/packaging/<page>.html  # Then fetch only what you need
+```
+
+## Golden Rule
+**Match existing patterns**: Match patterns from the docs and other packages. Pretty much anything you might need todo has already been done well.
diff --git a/packaging/src/environment-setup.md b/packaging/src/environment-setup.md
@@ -81,3 +81,54 @@ start-cli --version
 
 > [!TIP]
 > If any command is not found, revisit the installation steps for that tool and ensure it is on your system PATH.
+
+## Coding with Claude (Recommended)
+
+AI coding tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code) can dramatically accelerate your packaging workflow. To get the best results, set up a workspace that gives Claude direct access to the packaging guide.
+
+### 1. Create a workspace directory
+
+Create a directory that will serve as your AI-assisted workspace. This is **not** inside your package repo — it sits alongside it.
+
+```
+mkdir my-workspace && cd my-workspace
+```
+
+### 2. Clone the docs
+
+Clone the Start9 docs repo so Claude can read the packaging guide locally:
+
+```
+git clone https://github.com/Start9Labs/docs.git start-docs
+```
+
+### 3. Add a CLAUDE.md
+
+> [!IMPORTANT]
+> This is critical. Without this file, Claude will not know how to package a service for StartOS.
+
+Download the provided `CLAUDE.md` and place it in your workspace root:
+
+<a href="SAMPLE-CLAUDE.txt" download="CLAUDE.md" style="display:inline-block;padding:0.5em 1.2em;background:#58a6ff;color:#fff;border-radius:6px;text-decoration:none;font-weight:600">Download CLAUDE.md</a>
+
+This file instructs Claude to use the local packaging guide as its primary reference.
+
+### 4. Add your package repo
+
+Clone or create your package repo inside the workspace:
+
+```
+git clone https://github.com/user/my-service-startos.git
+```
+
+Your workspace should look like this:
+
+```
+my-workspace/
+├── CLAUDE.md            ← AI instructions (not committed anywhere)
+├── start-docs/          ← packaging guide for Claude to read
+└── my-service-startos/  ← your package repo
+```
+
+> [!NOTE]
+> Do not put `start-docs/` or `CLAUDE.md` inside your package repo. They live alongside it in the workspace so they don't pollute your package's git history.
diff --git a/packaging/src/file-models.md b/packaging/src/file-models.md
@@ -79,21 +79,25 @@ export const configYaml = FileHelper.yaml(
 
 ```typescript
 // One-time read (no restart on change) - returns null if file doesn't exist
-const store = await storeJson.read((s) => s).once()
+const store = await storeJson.read().once()
 
 // Handle missing file with nullish coalescing
 const keys = (await authorizedKeysFile.read().once()) ?? []
 
 // Reactive read (service restarts if value changes)
-const store = await storeJson.read((s) => s).const(effects)
+const store = await storeJson.read().const(effects)
 
 // Read only specific fields (subset reading)
 const password = await storeJson.read((s) => s.adminPassword).once()
 
-// Reactive subset read
+// Reactive subset read - daemon only restarts if secretKey changes
 const secretKey = await storeJson.read((s) => s.secretKey).const(effects)
 ```
 
+> [!WARNING]
+> Never use an identity mapper like `.read((s) => s)`. Either omit the mapper to get the full object (`.read()`) or use it to extract a specific field (`.read((s) => s.someField)`).
+
+
 ### Subset Reading
 
 Use mapping to retrieve only specific fields rather than entire files:
@@ -147,26 +151,41 @@ const shape = object({
 When an upstream service reads a config file (TOML, YAML, JSON, etc.), model that file directly with `FileHelper` rather than storing values in `store.json` and passing them as environment variables. A direct FileModel provides:
 
 - **Two-way binding**: Actions can read and write the upstream config file directly.
-- **Simpler main.ts**: No need to read from store, build env vars, and pass them to the daemon. Just write the FileModel to the subcontainer rootfs.
+- **Simpler main.ts**: Mount the config file from the volume into the subcontainer. No need to read and regenerate it.
 - **Easy user configuration**: Exposing config options via Actions is as simple as `configToml.merge(effects, { key: newValue })`.
 
 Use `store.json` only for internal package state that has no upstream config file equivalent (e.g., a generated PostgreSQL password that the upstream service doesn't read from its own config file).
 
 ```typescript
 // GOOD: Model the upstream config directly
 export const configToml = FileHelper.toml(
-  { base: sdk.volumes['mcaptcha-data'], subpath: 'config.toml' },
+  { base: sdk.volumes['my-data'], subpath: 'config.toml' },
   shape,
 )
 
-// In main.ts, write to subcontainer rootfs
-await writeFile(`${appSub.rootfs}/etc/mcaptcha/config.toml`,
-  await configToml.read((c) => c).const(effects))
+// In main.ts, mount the volume so the config file is accessible in the subcontainer.
+// You can mount the individual file or an entire directory that contains it.
+const appSub = await sdk.SubContainer.of(effects, { imageId: 'my-app' },
+  sdk.Mounts.of().mountVolume({
+    volumeId: 'my-data',
+    subpath: 'config.toml',
+    mountpoint: '/etc/my-app/config.toml',
+    readonly: false,
+    type: 'file',
+  }),
+  'my-app-sub',
+)
+
+// Reactive read triggers daemon restart when config changes (e.g. via actions)
+await configToml.read((c) => c.some_mutable_setting).const(effects)
 
 // In an action, toggle a setting directly
 await configToml.merge(effects, { allow_registration: !current })
 ```
 
+> [!WARNING]
+> Do NOT read a FileModel in main.ts and then write it back to the subcontainer rootfs. The file already lives on the volume — just mount it.
+
 ## Common Patterns
 
 ### Optional Fields with Defaults
diff --git a/packaging/src/main.md b/packaging/src/main.md
@@ -232,34 +232,24 @@ sdk.Mounts.of()
 
 ## Writing to Subcontainer Rootfs
 
-For config files that are regenerated on every startup, write directly to the subcontainer's rootfs instead of using volume mounts. This is simpler and avoids file mount issues:
+For config files that are *generated from code* on every startup (e.g., a Python settings file built from hostnames and secrets), write directly to the subcontainer's rootfs:
 
 ```typescript
-// Create subcontainer first
-const appSub = await sdk.SubContainer.of(
-  effects,
-  { imageId: "my-service" },
-  sdk.Mounts.of().mountVolume({
-    volumeId: "main",
-    subpath: null,
-    mountpoint: "/data",
-    readonly: false,
-  }),
-  "my-service-sub",
-);
-
-// Write config directly to subcontainer rootfs
+// Write a generated config to subcontainer rootfs
 await writeFile(
   `${appSub.rootfs}/app/config.py`,
   generateConfig({ secretKey, allowedHosts }),
 );
 ```
 
+> [!WARNING]
+> If the config file is managed by a FileModel, do NOT read it and write it back to rootfs. Mount it from the volume instead — the file already exists there.
+
 **When to use rootfs vs volume mounts:**
 
-- **Rootfs**: Ephemeral config files regenerated on each startup (secrets, hostnames, etc.)
-- **Volume mount (directory)**: Persistent data that survives restarts (databases, user files)
-- **Volume mount (file)**: Persistent config that users might edit (requires `type: 'file'`)
+- **Rootfs**: Config files *generated from code* that don't exist on a volume (e.g., built from hostnames, env vars, or templates)
+- **Volume mount (directory)**: Mount a directory that contains the config file alongside other persistent data. The config file is just one of many files in the mounted directory.
+- **Volume mount (file)**: Mount a single config file with `type: 'file'` when the config lives on a volume that is otherwise unrelated to the container's filesystem.
 
 ## Executing Commands in SubContainers
 
diff --git a/packaging/src/manifest.md b/packaging/src/manifest.md
@@ -44,12 +44,11 @@ export const manifest = setupManifest({
   id: 'my-service',
   title: 'My Service',
   license: 'MIT',
-  wrapperRepo: 'https://github.com/Start9Labs/my-service-startos',
+  packageRepo: 'https://github.com/Start9Labs/my-service-startos',
   upstreamRepo: 'https://github.com/original/my-service',
-  supportSite: 'https://docs.example.com/',
-  marketingSite: 'https://example.com/',
+  marketingUrl: 'https://example.com/',
   donationUrl: null,
-  docsUrl: 'https://docs.example.com/guides',
+  docsUrls: ['https://docs.example.com/guides'],
   description: { short, long },
   volumes: ['main'],
   images: {
@@ -74,12 +73,11 @@ export const manifest = setupManifest({
 | `id`                | Unique identifier (lowercase, hyphens allowed)         |
 | `title`             | Display name shown in UI                               |
 | `license`           | SPDX identifier (`MIT`, `Apache-2.0`, `GPL-3.0`, etc.) |
-| `wrapperRepo`       | URL to the StartOS wrapper repository                  |
+| `packageRepo`       | URL to the StartOS package repository                  |
 | `upstreamRepo`      | URL to the original project repository                 |
-| `supportSite`       | URL for user support                                   |
-| `marketingSite`     | URL for the project's main website                     |
+| `marketingUrl`      | URL for the project's main website                     |
 | `donationUrl`       | Donation URL or `null`                                 |
-| `docsUrl`           | URL to **upstream** documentation (not wrapper docs)   |
+| `docsUrls`          | Array of URLs to **upstream** documentation            |
 | `description.short` | Locale object (see `manifest/i18n.ts`)                 |
 | `description.long`  | Locale object (see `manifest/i18n.ts`)                 |
 | `volumes`           | Storage volumes (usually `['main']`)                   |
@@ -89,10 +87,13 @@ export const manifest = setupManifest({
 
 ## License
 
-Check the upstream project's LICENSE file and use the correct SPDX identifier (e.g., `MIT`, `Apache-2.0`, `GPL-3.0`). Create a symlink from your project root to the upstream license:
+Check the upstream project's LICENSE file and use the correct SPDX identifier (e.g., `MIT`, `Apache-2.0`, `GPL-3.0`). If you have a git submodule, symlink to its license. Otherwise, copy the license text directly from the upstream repository:
 
 ```bash
+# With submodule
 ln -sf upstream-project/LICENSE LICENSE
+
+# Without submodule -- copy from upstream repo
 ```
 
 ## Icon
@@ -250,9 +251,13 @@ alerts: {
 
 ## Volumes
 
-Storage volumes for persistent data. Usually just `['main']`:
+Storage volumes for persistent data. When possible, prefer matching the upstream project's volume naming convention for clarity:
 
 ```typescript
+// If upstream docker-compose uses a volume named "mcaptcha-data"
+volumes: ['mcaptcha-data'],
+
+// Simple services can use 'main'
 volumes: ['main'],
 ```
 
@@ -262,7 +267,7 @@ For services needing separate storage areas:
 volumes: ['main', 'db', 'config'],
 ```
 
-Reference these in `main.ts` mounts as `'main'`, `'db'`, `'config'`.
+Reference these in `main.ts` mounts by the volume ID you chose.
 
 ## Dependencies
 
