@akanjs/cli 3.0.0-beta.2 → 3.0.0-beta.20

package/skills/akan-store/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: akan-store
+description: "Fill in a module store, or call module data and actions from UI — what store() already generates (CRUD, form setters, slice actions) and what belongs in your subclass."
+---
+
+# Akan store: what is already generated
+
+`class CommentStore extends store(sig.comment, () => ({ /* extra state */ })) { /* extra actions */ }`
+gives you the whole CRUD and form surface for free. **Redeclaring any of it is a typecheck error
+("already exists"), and the fix is to delete your version and call the generated one** — never rename around
+it, never cast, never reimplement.
+
+For a model `comment` (`<Slice>` is a signal slice suffix, e.g. `InPublic`):
+
+## Generated actions — `st.do.*`
+
+- write: `createComment(input)`, `updateComment(id, input)`, `removeComment(id)`
+- form: `newComment()`, `editComment(model)`, `writeOnComment(path, value)`, `set<Field>OnComment(value)`,
+  `add<Field>OnComment(value)` / `sub<Field>OnComment(idx)` for arrays, `upload<Field>OnComment(fileList)`
+  for file fields, `checkCommentSubmitable()`, `submitComment()`, `createCommentInForm()`,
+  `updateCommentInForm()`
+- single: `viewComment(model)`, `mergeComment(model, data)`, `setComment(...models)`, `resetComment()`
+- per slice: `initComment<Slice>(...args)`, `refreshComment<Slice>()`, `selectComment<Slice>(model)`,
+  `setPageOfComment<Slice>(page)`, `loadMoreOfComment<Slice>()`, `setLimitOfComment<Slice>(limit)`,
+  `setQueryArgsOfComment<Slice>(...)`, `setSortOfComment<Slice>(sort)`
+
+## Generated state — `st.use.*`
+
+`comment`, `commentLoading`, `commentForm`, `commentFormLoading`, `commentSubmit`, `commentModal`,
+`commentViewAt`, `commentOperation`; per slice `commentList<Slice>`, `commentListLoading<Slice>`,
+`commentInitList<Slice>`, `commentSelection<Slice>`, `commentInsight<Slice>`, `pageOfComment<Slice>`,
+`lastPageOfComment<Slice>`, `hasMoreOfComment<Slice>`, `limitOfComment<Slice>`, `sortOfComment<Slice>`.
+
+## What your subclass is for
+
+Only what the generated set does not cover: extra client state, a multi-step or cross-model workflow, and
+calls to the non-CRUD endpoints you added in the signal. Each is an `async` method using `this.set(...)` /
+`this.get()` / `this.pick(...)`.
+
+To reach another store, cast `this`: `import type { RootStore } from "../st"`, then
+`(this as unknown as RootStore).logout()` to call its action or `(this as unknown as RootStore).set({ … })` /
+`.get()` to write or read its state. Every store is mixed into one root at runtime, so the cast only tells the
+type what `this` already is. Keep it `import type` — `st.ts` imports every store, so a value import is a cycle.
+
+A store that needs none of this stays empty. `store(sig.comment, () => ({}))` with an empty body is the
+correct, complete result — an empty store is not an unfinished one.
+
+## The rule the linter enforces
+
+- **An action returns nothing.** Every method dispatches through `st.do.<action>()` and is typed `void`, so a
+  returned value is unreachable. Write it into state with `this.set({ … })`.
+
+## From UI
+
+Read with `st.use.commentListInPublic()`, act with `st.do.createComment(input)` / `st.do.submitComment()`.
+Do not wrap a generated action in a store method just to rename it.
+
+**Pass a form setter by reference**: `onChange={st.do.setTypeOnComment}`, never
+`onChange={(v) => st.do.setTypeOnComment(v)}`. The two run identically, but the arrow is an anonymous
+closure, so the control emits no `data-akan-action` and publishes no agent tool for the field —
+`no-unpublished-form-setter.grit` fails the build on it.
+
+## Signal side
+
+The scaffolded `slice(…, { guards: { root, get, cru } })` already exposes get / list / create / update /
+remove. Add a query or mutation only for behaviour beyond CRUD, and give it its own `guards` array — a
+custom endpoint never inherits the slice's.

package/skills/akan-ui/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: akan-ui
+description: "Build Akan pages and components: the server-by-default rule, the Unit/View vs Template/Zone/Util split, forms, and what never to hand-roll."
+---
+
+# Akan UI
+
+A new View / Unit / Template / Zone / Util for an existing module comes from the `create-ui` workflow (the
+`akan-scaffold` skill). Edit the scaffolded component instead of authoring one from scratch.
+
+## The boundary is mechanical, not a judgement call
+
+| role | side | directive |
+| --- | --- | --- |
+| `<Model>.Unit.tsx`, `<Model>.View.tsx` | server | never `"use client"` |
+| `<Model>.Template.tsx`, `<Model>.Zone.tsx`, `<Model>.Util.tsx` | client | `"use client"` on line 1 |
+| `page/**` | server | never |
+
+**Server is the default and `"use client"` is a cost you justify per component.** A component earns the
+directive only by using a hook, a JSX event handler, the store, a browser global, or a client-only package.
+Rendering markup, reading a param, calling `l()`, and mapping over data are all server work. Measure with
+`akan quality ssr`; treat 50% server share as the floor and a falling share as a regression.
+
+Four moves that keep markup on the server: wrap the interaction and render `children` untouched; split a
+compound component so only the provider holds state; fetch in the route and pass the result into a `Zone` as
+an `init` prop; push the boundary down to the leaf that needs it.
+
+## Never hand-roll these
+
+- loading / empty / list states → `Load.Units` / `Load.View` / `Load.Edit` with `renderItem`, `renderList`,
+  `renderView`, `renderEmpty`; `<Empty />` for a bare placeholder; `Model.New` / `Model.Edit` /
+  `Model.SureToRemove` for CRUD modals.
+- a mount-time fetch → the route calls `fetch.init<Model><Slice>(…)` before the first byte. A
+  `useEffect(…, [])` that loads data is flagged by `akan quality ssr`, and `fetch.init*` from a client file
+  fails lint outright.
+- a model field input → `Field.*`, never a bare `<input>`.
+- a mode switch → `Tab`, not a `useState`.
+
+## Component shape
+
+`export const X = ({ … }: XProps) => { return (…); };` — arrow const, block body. Never `React.FC`, never
+`defaultProps`, never `PropsWithChildren`; children are `children: ReactNode`. Declare
+`interface XProps` directly above the component with `className?: string` first.
+
+Conditional render is `cond ? <X/> : null`. **Never `{cond && <X/>}`** — in a `className` context it renders
+the literal string `"false"`.
+
+## Classes
+
+Never hand-order Tailwind classes; the formatter sorts them and its output is correct. Stay inside the
+semantic token vocabulary — `bg-primary`, `text-foreground/70` — because a raw palette class (`bg-blue-500`),
+an arbitrary colour (`bg-[#3b82f6]`), a daisyUI legacy class, and a colour literal in `style={{…}}` all
+render no CSS and fail lint. Reach for `cn` only for a conditional or to merge an incoming `className`, and
+merge the caller last.
+
+## Forms
+
+Store-driven end to end: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`, **the setter passed by
+reference**. An inline arrow silently drops the control's agent annotation and fails
+`no-unpublished-form-setter.grit`. Nested rows use `st.do.writeOnX("payments.3.name", v)`.
+
+Full detail: `get_guideline` with `ssrRule`, `componentRule`, `cssRule`, `recipeRule`, or the per-role
+`modelUnit` / `modelView` / `modelZone` / `modelTemplate` / `modelUtil`.

package/skills/akan-validate/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: akan-validate
+description: "Run the akan check loop after editing and fix each failure class the right way — no silencing, no lint-disable, no gaming the checker."
+---
+
+# Akan validation loop
+
+## One call does the whole chain
+
+`akan_verify` runs sync → lint → typecheck → `quality ssr` over everything the working tree has changed, in
+the right order, and reports only what failed. **Call it after editing, before you say you are done.** It
+also runs itself at the end of a turn that changed source, so a failure comes back to you either way.
+
+The same chain by hand, for the app you are editing:
+
+- `akan sync <app>` — after adding, renaming, or deleting any file. Regenerates the barrels.
+- `akan lint <app>` — fast; run after every edit. Prints up to 200 diagnostics.
+- `akan typecheck <app>` — the client/server boundary violations land here, not in lint.
+- `akan quality ssr` — only when you wrote or changed a `.tsx`. Did the server share hold?
+- `akan build <app>` — the full production build; slower, and only when the build itself is in question.
+
+Raw `tsc` misses the generated barrels and reports false errors. Do not reach for it.
+
+## Fixing rules
+
+**Apply the real fix the rule intends. Do not silence the checker.** No blanket lint-disable, no throwaway
+re-export, no export-in-place trick, no `as any`, no non-null assertion. Gaming a check is a defect, not a
+fix. When a suppression is genuinely right it carries a reason:
+`// biome-ignore lint/<rule>: <why>` — and a grit plugin diagnostic is suppressed as `lint/plugin`, not the
+bare `plugin` category Biome's own message suggests.
+
+Common classes and their real fix:
+
+| symptom | fix |
+| --- | --- |
+| a member "already exists" or conflicts with the base class | you redeclared something Akan generates, usually store CRUD. **Delete your version** and call the generated one — do not rename, cast, or suppress. See `akan-store`. |
+| `throw new Error` | a typed `Err` with a dictionary key. See `akan-err`. |
+| an edit to a generated file | regenerate instead: `akan sync <app>` or `repair_generated`. |
+| a file in the wrong place | relocate to `common/` / `webkit/` / `srvkit/` / `ui/`. Never a sibling helper `.ts` inside `lib/<model>/`. |
+| a missing dependency | declare it in the owning app or lib `package.json`. See `akan-deps`. |
+| a Tailwind class order or colour complaint | let the formatter sort; use semantic tokens. See `akan-ui`. |
+
+Re-run until clean. If a failure is genuinely outside the scope of what you changed, say so in your reply
+instead of forcing it.

package/{subspace.command-fwjfcts7.js → subspace.command-ckcbwfp1.js}

@@ -1,25 +1,28 @@
 // @bun
+import {
+  FileSys2
+} from "./index-5b6tavv3.js";
+import {
+  GlobalConfig
+} from "./index-22d57v4c.js";
 import {
   Workspace,
+  CommandContainer,
   runner,
   script,
   command
-} from "./index-mak3cd28.js";
-import {
-  FileSys
-} from "./index-q0y2jq9j.js";
+} from "./index-w2zdcw3k.js";
 import {
   Executor,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-2tv3fdx4.js";
-import"./index-6wwzs1bc.js";
+} from "./index-9d9bgcx4.js";
 import {
   SlicePlanner
-} from "./index-j9yhg404.js";
+} from "./index-xqjwd384.js";
 import {
   LibSource
-} from "./index-3d9y066c.js";
+} from "./index-bjwxs904.js";
 
 // pkgs/@akanjs/devkit/subspace.ts
 import { mkdir, readdir, rename, rm } from "fs/promises";
@@ -45,6 +48,9 @@ class Subspace {
   get apps() {
     return this.#declaration.apps;
   }
+  get workspaceId() {
+    return this.#declaration.workspaceId;
+  }
   get #remote() {
     return `subspace-${this.#declaration.name}`;
   }
@@ -111,16 +117,16 @@ class Subspace {
       return true;
     const normalize = (content) => {
       try {
-        const manifest = JSON.parse(content);
-        delete manifest[LibSource.manifestKey];
-        return JSON.stringify(manifest);
+        return LibSource.unstamped(content);
       } catch {
         return content;
       }
     };
     return normalize(theirs) !== normalize(ours);
   }
-  async#meaningfulFiles(ref, files) {
+  async#changedSliceFiles(ref, diffArgs) {
+    const files = (await this.#git(["diff", "--name-only", ...diffArgs])).split(`
+`).filter((file) => !!file.trim() && !this.#isSubspaceOwned(file));
     const kept = await Promise.all(files.map(async (file) => this.#isStamped(file) ? await this.#differsBeyondStamp(ref, file) : true));
     return files.filter((_, index) => kept[index]);
   }
@@ -133,14 +139,12 @@ class Subspace {
     if (!hasBranch)
       return { name: this.name, branch, hasBranch, anchor, behindPaths: [], driftedLibs: [] };
     const ref = `${this.#remote}/${branch}`;
-    const diff = await this.#git(["diff", "--name-only", "HEAD", ref, "--", ...paths]);
-    const behindPaths = await this.#meaningfulFiles(ref, diff.split(`
-`).filter((file) => !!file.trim()).filter((file) => !this.#isSubspaceOwned(file)));
+    const behindPaths = await this.#changedSliceFiles(ref, ["HEAD", ref, "--", ...paths]);
     const driftedLibs = libs.filter((lib) => behindPaths.some((file) => file.startsWith(`libs/${lib}/`)));
     return { name: this.name, branch, hasBranch, anchor, behindPaths, driftedLibs };
   }
   async#ensureClone(branch) {
-    if (!await FileSys.dirExists(path.join(this.#clonePath, ".git"))) {
+    if (!await FileSys2.dirExists(path.join(this.#clonePath, ".git"))) {
       await rm(this.#clonePath, { recursive: true, force: true });
       await mkdir(path.dirname(this.#clonePath), { recursive: true });
       await this.#workspace.spawn("git", ["clone", "--quiet", this.#declaration.repo, this.#clonePath]);
@@ -157,12 +161,12 @@ class Subspace {
     await rm(holdRoot, { recursive: true, force: true });
     for (const member of Subspace.memberDirs) {
       const memberRoot = path.join(this.#clonePath, member);
-      if (!await FileSys.dirExists(memberRoot))
+      if (!await FileSys2.dirExists(memberRoot))
         continue;
       for (const name of await readdir(memberRoot)) {
         for (const owned of Subspace.subspaceOwnedDirs) {
           const from = path.join(memberRoot, name, owned);
-          if (!await FileSys.dirExists(from))
+          if (!await FileSys2.dirExists(from))
             continue;
           const to = path.join(holdRoot, member, name, owned);
           await mkdir(path.dirname(to), { recursive: true });
@@ -185,14 +189,25 @@ class Subspace {
       const target = path.join(to, entry.name);
       if (entry.isDirectory())
         await Subspace.#copyMissing(source, target);
-      else if (!await FileSys.entryExists(target))
+      else if (!await FileSys2.entryExists(target))
         await rename(source, target);
     }
   }
   async#extract(paths, excludes = []) {
-    const pathspec = paths.map((entry) => `'${entry}'`).join(" ");
-    const excludeArgs = excludes.map((entry) => `--exclude='${entry}'`).join(" ");
-    await this.#workspace.exec(`git archive HEAD -- ${pathspec} | tar -x -C '${this.#clonePath}' ${excludeArgs}`.trim());
+    const archivePath = path.relative(this.#workspace.workspaceRoot, `${this.#clonePath}.tar`);
+    await this.#workspace.spawn("git", ["archive", "-o", archivePath, "HEAD", "--", ...paths]);
+    try {
+      await this.#workspace.spawn("tar", [
+        "-x",
+        "-f",
+        archivePath,
+        "-C",
+        this.#clonePath,
+        ...excludes.map((entry) => `--exclude=${entry}`)
+      ]);
+    } finally {
+      await rm(path.join(this.#workspace.workspaceRoot, archivePath), { force: true });
+    }
   }
   #localEnv() {
     const { serveDomain } = WorkspaceExecutor.getBaseDevEnv();
@@ -207,32 +222,32 @@ class Subspace {
   }
   async#writeLocalEnv() {
     const excludePath = path.join(this.#clonePath, ".git/info/exclude");
-    const exclude = await FileSys.fileExists(excludePath) ? await FileSys.readText(excludePath) : "";
+    const exclude = await FileSys2.fileExists(excludePath) ? await FileSys2.readText(excludePath) : "";
     if (!exclude.split(`
 `).includes("/.env")) {
       await mkdir(path.dirname(excludePath), { recursive: true });
-      await FileSys.writeText(excludePath, exclude.trim() ? `${exclude.replace(/\n*$/, `
+      await FileSys2.writeText(excludePath, exclude.trim() ? `${exclude.replace(/\n*$/, `
 `)}/.env
 ` : `/.env
 `);
     }
     const envPath = path.join(this.#clonePath, ".env");
-    if (await FileSys.fileExists(envPath))
+    if (await FileSys2.fileExists(envPath))
       return;
     const lines = Object.entries(this.#localEnv()).map(([key, value]) => `${key}=${value}`);
-    await FileSys.writeText(envPath, `${lines.join(`
+    await FileSys2.writeText(envPath, `${lines.join(`
 `)}
 `);
   }
   async#rewriteManifest(plans) {
     const manifestPath = path.join(this.#clonePath, "package.json");
-    if (!await FileSys.fileExists(manifestPath))
+    if (!await FileSys2.fileExists(manifestPath))
       return [];
-    const rootPackageJson = await FileSys.readJson(manifestPath);
+    const rootPackageJson = await FileSys2.readJson(manifestPath);
     const { packageJson, pruned, warnings } = await SlicePlanner.pruneDependencies(this.#workspace, rootPackageJson, plans.flatMap((plan) => plan.requiredDependencies));
     for (const warning of warnings)
       this.#workspace.logger.warn(warning);
-    await FileSys.writeJson(manifestPath, {
+    await FileSys2.writeJson(manifestPath, {
       ...packageJson,
       name: this.name,
       description: `${this.name} workspace`
@@ -259,11 +274,10 @@ class Subspace {
   }
   async#rewriteGitignore() {
     const gitignorePath = path.join(this.#clonePath, ".gitignore");
-    if (!await FileSys.fileExists(gitignorePath))
+    if (!await FileSys2.fileExists(gitignorePath))
       return;
     const [begin = "", end = ""] = Subspace.secretsMarkers;
-    const lines = (await FileSys.readText(gitignorePath)).split(`
-`);
+    const lines = (await FileSys2.readText(gitignorePath)).split(/\r?\n/);
     const beginIdx = lines.indexOf(begin);
     const endIdx = lines.indexOf(end);
     const filtered = beginIdx >= 0 && endIdx > beginIdx ? [
@@ -271,7 +285,7 @@ class Subspace {
       ...lines.slice(beginIdx + 1, endIdx).filter((line) => this.#declaration.apps.some((app) => line.startsWith(`apps/${app}/`))),
       ...lines.slice(endIdx)
     ] : lines;
-    await FileSys.writeText(gitignorePath, filtered.filter((line) => line.trim() !== "**/bun.lock").join(`
+    await FileSys2.writeText(gitignorePath, filtered.filter((line) => line.trim() !== "**/bun.lock").join(`
 `));
   }
   async#rewriteWorkspaceSection(libs) {
@@ -282,27 +296,27 @@ class Subspace {
     ];
     for (const file of ["AGENTS.md", "CLAUDE.md"]) {
       const filePath = path.join(this.#clonePath, file);
-      if (!await FileSys.fileExists(filePath))
+      if (!await FileSys2.fileExists(filePath))
         continue;
-      const content = await FileSys.readText(filePath);
+      const content = await FileSys2.readText(filePath);
       const rewritten = replacements.reduce((text, [pattern, value]) => text.replace(pattern, value), content);
       if (rewritten !== content)
-        await FileSys.writeText(filePath, rewritten);
+        await FileSys2.writeText(filePath, rewritten);
     }
   }
   async#stampLib(clone, lib, branch) {
     const manifestPath = path.join(this.#clonePath, "libs", lib, "package.json");
-    if (!await FileSys.fileExists(manifestPath))
+    if (!await FileSys2.fileExists(manifestPath))
       return;
     const origin = `${this.#workspace.repoName}#${branch}`;
     const sha = await this.headSha();
     const [hash, previous] = await Promise.all([this.#hashLib(clone, lib), this.#committedStamp(clone, lib)]);
-    const manifest = await FileSys.readJson(manifestPath);
+    const manifest = await FileSys2.readJson(manifestPath);
     const akan = manifest[LibSource.manifestKey] ?? {};
     const unchanged = previous?.origin === origin && previous.sha === sha && previous.hash === hash;
     const syncedAt = unchanged ? previous.syncedAt : new Date().toISOString();
     manifest[LibSource.manifestKey] = { ...akan, source: { origin, sha, hash, syncedAt } };
-    await FileSys.writeJson(manifestPath, manifest);
+    await FileSys2.writeJson(manifestPath, manifest);
   }
   async#committedStamp(clone, lib) {
     try {
@@ -325,22 +339,9 @@ class Subspace {
       `libs/${lib}`
     ]);
     const candidates = listed.split("\x00").filter((file) => !!file && !this.#isSubspaceOwned(file)).sort();
-    const present = await Promise.all(candidates.map(async (file) => await FileSys.entryExists(path.join(this.#clonePath, file))));
+    const present = await Promise.all(candidates.map(async (file) => await FileSys2.entryExists(path.join(this.#clonePath, file))));
     const files = candidates.filter((_, index) => present[index]);
-    const hasher = new Bun.CryptoHasher("sha256");
-    for (const file of files) {
-      const content = await FileSys.readText(path.join(this.#clonePath, file));
-      hasher.update(file);
-      hasher.update("\x00");
-      if (file === `libs/${lib}/package.json`) {
-        const manifest = JSON.parse(content);
-        delete manifest[LibSource.manifestKey];
-        hasher.update(JSON.stringify(manifest));
-      } else
-        hasher.update(content);
-      hasher.update("\x00");
-    }
-    return hasher.digest("hex").slice(0, 32);
+    return await LibSource.hashFiles(files, `libs/${lib}/package.json`, (file) => FileSys2.readText(path.join(this.#clonePath, file)));
   }
   async diff(branch, filter) {
     if (!await this.fetch(branch))
@@ -359,10 +360,7 @@ class Subspace {
     if (!scoped.length)
       return { files: [], patch: "" };
     const from = `${this.#remote}/${branch}`;
-    const pathspec = filter ? [filter] : scoped;
-    const names = await this.#git(["diff", "--name-only", from, "HEAD", "--", ...pathspec]);
-    const files = await this.#meaningfulFiles(from, names.split(`
-`).filter((file) => !!file.trim()).filter((file) => !this.#isSubspaceOwned(file)));
+    const files = await this.#changedSliceFiles(from, [from, "HEAD", "--", ...filter ? [filter] : scoped]);
     if (!files.length)
       return { files: [], patch: "" };
     return { files, patch: await this.#git(["diff", from, "HEAD", "--", ...files]) };
@@ -416,7 +414,7 @@ class Subspace {
     };
   }
   async#writeAnchorFile(branch) {
-    await FileSys.writeJson(path.join(this.#clonePath, Subspace.anchorFile), {
+    await FileSys2.writeJson(path.join(this.#clonePath, Subspace.anchorFile), {
       workspace: this.#workspace.repoName,
       hubSha: await this.headSha(),
       branch,
@@ -453,7 +451,7 @@ class Subspace {
   async#savePatch(range, files, label) {
     const patchPath = path.join(this.#workspace.workspaceRoot, ".akan/subspace", `${this.name}-${label}.patch`);
     await mkdir(path.dirname(patchPath), { recursive: true });
-    await FileSys.writeText(patchPath, await this.#git(["diff", range, "--", ...files]));
+    await FileSys2.writeText(patchPath, await this.#git(["diff", range, "--", ...files]));
     return { path: path.relative(this.#workspace.workspaceRoot, patchPath), absolute: patchPath, files };
   }
 }
@@ -522,6 +520,23 @@ function formatSubspacePullResult(result) {
   return sections.join(`
 `);
 }
+function formatSubspaceEnvUpload(result) {
+  const sections = [
+    `Akan Subspace Env Upload \u2014 ${result.name}`,
+    `cloud workspace: ${result.workspaceId} \xB7 host: ${result.host}`,
+    "",
+    ...result.outcome === "cancelled" ? ["  cancelled \u2014 the subspace's env archive is untouched."] : [
+      `Uploaded (${result.files.length}), replacing that workspace's whole archive:`,
+      "",
+      ...result.files.map((file) => `  ${file}`),
+      "",
+      `  apps: ${result.apps.join(", ")}`,
+      `  libs: ${result.libs.join(", ") || "(none)"}`
+    ]
+  ];
+  return sections.join(`
+`);
+}
 function formatSubspaceDiff(result) {
   const total = result.app.files.length + result.libs.files.length;
   const sections = [
@@ -558,7 +573,7 @@ class SubspaceConfig {
   static defaultPushableBranches = ["main", "develop", "debug"];
   static async from(workspace) {
     const configPath = path2.join(workspace.workspaceRoot, SubspaceConfig.fileName);
-    if (!await FileSys.fileExists(configPath))
+    if (!await FileSys2.fileExists(configPath))
       return null;
     const input = await import(configPath).then((mod) => mod.default);
     return new SubspaceConfig(input);
@@ -575,6 +590,7 @@ class SubspaceConfig {
   #assertValid() {
     const seenNames = new Set;
     const appOwners = new Map;
+    const idOwners = new Map;
     for (const subspace of this.subspaces) {
       if (!subspace.name || !subspace.repo)
         throw new Error(`${SubspaceConfig.fileName}: every subspace needs a name and a repo`);
@@ -589,6 +605,12 @@ class SubspaceConfig {
           throw new Error(`${SubspaceConfig.fileName}: app "${app}" is claimed by both "${owner}" and "${subspace.name}"`);
         appOwners.set(app, subspace.name);
       }
+      if (!subspace.workspaceId)
+        continue;
+      const idOwner = idOwners.get(subspace.workspaceId);
+      if (idOwner)
+        throw new Error(`${SubspaceConfig.fileName}: subspaces "${idOwner}" and "${subspace.name}" declare the same workspaceId`);
+      idOwners.set(subspace.workspaceId, subspace.name);
     }
   }
   select(names) {
@@ -625,10 +647,12 @@ class SubspaceRunner extends runner("subspace") {
     const branch = (await workspace.spawn("git", ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
     return { config, subspaces, branch };
   }
+  static #isInteractive() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+  }
   async selectNames(workspace, action) {
     const config = await this.config(workspace);
-    const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
-    return await SubspaceRunner.chooseNames(config, action, { interactive });
+    return await SubspaceRunner.chooseNames(config, action, { interactive: SubspaceRunner.#isInteractive() });
   }
   static async chooseNames(config, action, { interactive, prompts }) {
     const multiple = SubspaceRunner.multiTargetActions.includes(action);
@@ -676,6 +700,43 @@ class SubspaceRunner extends runner("subspace") {
       throw new Error(`Unknown subspace "${name}"`);
     return await subspace.pull(branch, { adoptLibs });
   }
+  async uploadEnv(workspace, name, { host, force }) {
+    const config = await this.config(workspace);
+    const [declaration] = config.select([name]);
+    if (!declaration)
+      throw new Error(`Unknown subspace "${name}"`);
+    const subspace = new Subspace(workspace, config, declaration);
+    const { workspaceId } = subspace;
+    if (!workspaceId)
+      throw new Error(`Subspace "${subspace.name}" declares no workspaceId. Add its cloud workspace id to ${SubspaceConfig.fileName}.`);
+    if (workspaceId === workspace.getWorkspaceId({ allowEmpty: true }))
+      throw new Error(`Subspace "${subspace.name}" declares this workspace's own id. Uploading a slice there would replace the workspace's env archive with a subset of it.`);
+    const apps = subspace.apps;
+    const asked = await SubspaceRunner.confirmEnvUpload({ name: subspace.name, workspaceId, apps, force }, { interactive: SubspaceRunner.#isInteractive() });
+    if (!asked)
+      return { name: subspace.name, workspaceId, host, apps, libs: [], outcome: "cancelled", files: [] };
+    const { libs } = await subspace.slice();
+    const { CloudScript } = await import("./cloud.script-bkbpcr96.js");
+    const { files } = await CommandContainer.get(CloudScript).uploadEnv(workspace, {
+      host,
+      workspaceId,
+      scope: { apps, libs },
+      archivePath: `local/env.${subspace.name}.tar`
+    });
+    return { name: subspace.name, workspaceId, host, apps, libs, outcome: "uploaded", files };
+  }
+  static async confirmEnvUpload({ name, workspaceId, apps, force }, { interactive, prompts }) {
+    if (force)
+      return true;
+    const target = `subspace "${name}" (cloud workspace ${workspaceId})`;
+    if (!interactive)
+      throw new Error(`Refusing to replace the env archive of ${target} with no terminal to ask in. Pass --force.`);
+    const { confirm } = prompts ?? await loadPrompts();
+    return await confirm({
+      message: `Replace the env archive of ${target} with this workspace's env for ${apps.join(", ")} and the libraries they pull in?`,
+      default: false
+    });
+  }
 }
 
 // pkgs/@akanjs/cli/subspace/subspace.script.ts
@@ -706,6 +767,10 @@ class SubspaceScript extends script("subspace", [SubspaceRunner]) {
     spinner.succeed(`${total} file(s) differ (${result.libs.files.length} in shared libraries)`);
     Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatSubspaceDiff(result));
   }
+  async uploadEnv(workspace, name, { host, force, format }) {
+    const result = await this.subspaceRunner.uploadEnv(workspace, name, { host, force });
+    Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatSubspaceEnvUpload(result));
+  }
   async pull(workspace, name, { adoptLibs, format }) {
     const spinner = workspace.spinning(`Pulling customer commits from ${name}...`);
     const result = await this.subspaceRunner.pull(workspace, name, { adoptLibs });
@@ -719,7 +784,7 @@ class SubspaceCommand extends command("subspace", [SubspaceScript], ({ public: t
   subspace: target({ desc: "Mirror apps and libraries between this workspace and the customer repos it serves" }).arg("action", String, {
     desc: "subspace action; status-all and push-all take every declared subspace",
     default: "status",
-    enum: ["status", "status-all", "diff", "push", "push-all", "pull"]
+    enum: ["status", "status-all", "diff", "push", "push-all", "pull", "upload-env"]
   }).arg("subspace", String, {
     desc: "subspace name; asks which one(s) when omitted, and is refused by status-all / push-all",
     nullable: true
@@ -727,12 +792,16 @@ class SubspaceCommand extends command("subspace", [SubspaceScript], ({ public: t
     flag: "y",
     desc: "run bun install + akan sync in the subspace before committing",
     default: true
-  }).option("adoptLibs", Boolean, { desc: "pull: also apply the subspace's library edits", default: false }).option("path", String, { desc: "diff: limit to one path", nullable: true }).exec(async function(action, subspace, workspace, format, verify, adoptLibs, filePath) {
+  }).option("adoptLibs", Boolean, { desc: "pull: also apply the subspace's library edits", default: false }).option("path", String, { desc: "diff: limit to one path", nullable: true }).option("host", String, { desc: "upload-env: host of the cloud to target", default: GlobalConfig.akanCloudHost }).option("force", Boolean, {
+    flag: "F",
+    desc: "upload-env: replace the subspace's env archive without asking",
+    default: false
+  }).exec(async function(action, subspace, workspace, format, verify, adoptLibs, filePath, host, force) {
     const output = format;
     const all = action === "status-all" || action === "push-all";
     const base = all ? action.slice(0, -"-all".length) : action;
-    if (base !== "status" && base !== "diff" && base !== "push" && base !== "pull")
-      throw new Error(`Unknown subspace action: ${action}. Use status, status-all, diff, push, push-all or pull.`);
+    if (base !== "status" && base !== "diff" && base !== "push" && base !== "pull" && base !== "upload-env")
+      throw new Error(`Unknown subspace action: ${action}. Use status, status-all, diff, push, push-all, pull or upload-env.`);
     if (all && subspace)
       throw new Error(`\`akan subspace ${action}\` takes no name. Run \`akan subspace ${base} ${subspace}\` instead.`);
     const names = subspace ? [subspace] : all ? [] : await this.subspaceScript.select(workspace, base);
@@ -746,6 +815,8 @@ class SubspaceCommand extends command("subspace", [SubspaceScript], ({ public: t
         throw new Error(`\`akan subspace ${base}\` needs a name \u2014 it is reviewed one repo at a time.`);
       if (base === "diff")
         await this.subspaceScript.diff(workspace, name, filePath, output);
+      else if (base === "upload-env")
+        await this.subspaceScript.uploadEnv(workspace, name, { host, force, format: output });
       else
         await this.subspaceScript.pull(workspace, name, { adoptLibs, format: output });
     }

package/templates/__scalar/__model__/__model__.abstract.md.template

@@ -0,0 +1,8 @@
+# <%= model %> Abstract
+
+<One sentence: the value this scalar holds, and what embeds it.>
+
+## Rules
+
+- <What a caller may assume about the value that the constant file cannot say: an order, a unit, a fixed value.>
+- <Two to five of them. A single field's meaning goes in a trailing comment beside it in the constant file.>