@pipod/cli 0.1.10 → 0.1.12

package/docs/config-simplification.md

@@ -115,15 +115,17 @@ ignored, except `--dry-run`/`--on`-with-fork which are usage errors.
   `--from-here`), `edit` (`--name/--description/--config/--init-script/--bake-script`;
   `--org` rejected — org-wide goes through `share`; whole-snapshot replace goes through `push`), `share` (one-way),
   `rm|delete [-y]`. A global `--yes` is honored (no false scope warning).
-- `push [template [<name>]|user|org]`: whole-bundle replace from the layer's
-  local source (project `.pi-pod/`+`.pi/`, user `~/.pi-pod`+`~/.pi/agent`, org
-  `~/.pi-pod/org/` or `--dir`), after a diff preview. `--with-secrets` uploads
-  env values (else a prompt per bundle); `-y` applies without confirming.
-- `pull [layer]`: reverse of push (same sources; `--dir` for org; `-y`).
+- `push [template [<name>]|user|org|policy]`: whole-bundle replace from the
+  layer's local source (project `.pi-pod/`+`.pi/`, user `~/.pi-pod`+`~/.pi/agent`,
+  org `~/.pi-pod/org/` or `--dir`, policy `policy.json` in that org directory),
+  after a diff preview. The policy is config only and validated by the server.
+  `--with-secrets` uploads env values (else a prompt per bundle); `-y` applies
+  without confirming.
+- `pull [layer]`: reverse of push (same sources; `--dir` for org and policy; `-y`).
   Client-only keys, host-coupled settings, and model credential values survive;
   server scripts with no local file warn instead of writing.
 - `diff [layer]`: same sources, secrets by name only; exit 1 on drift (`--dir`
-  for org; no `-y` — it never writes).
+  for org and policy; no `-y` — it never writes).
 - `settings <user|org> [show|edit|set <key> <json-value>]`: config-only
   compare-and-swap edits (scripts/Pi files untouched — that is `push`).
   `show` prints JSON; `edit` uses `$VISUAL`/`$EDITOR`; `set` takes a dotted key

package/docs/workspace-seeding.md

@@ -23,20 +23,23 @@ from a subdirectory seeds the whole repository and prints the subdirectory so it
 
 ## Clone or archive
 
-A clone is chosen only when it reproduces the host checkout exactly. Every check below fails
-closed into an archive with a human-readable reason (`pipod --dry-run` prints it):
+A clone is preferred when the pod can fetch the host's exact **committed HEAD**. Local
+staged, unstaged, and untracked changes do not prevent cloning and are **not copied** by a
+successful clone. The local checkout is left untouched. Every check below fails closed into
+an archive with a human-readable reason (`pipod --dry-run` prints it):
 
 1. inside a git work tree
 2. `origin` exists and rewrites to an `https://` URL (`git@host:x/y.git` and `ssh://` are rewritten; local paths cannot be cloned by a pod)
 3. HEAD is on a branch
-4. no modified, staged, or untracked non-ignored files
-5. the branch has an upstream with no unpushed commits
-6. no initialized submodules, no Git LFS attributes
-7. the pod's egress policy admits the remote host
-8. a live `git ls-remote` shows the remote branch at exactly the local HEAD commit
+4. the branch has an upstream with no unpushed commits
+5. no initialized submodules, no Git LFS attributes
+6. the pod's egress policy admits the remote host
+7. a live `git ls-remote` shows the remote branch at exactly the local HEAD commit
 
 The server clones that exact commit into the empty workdir. If the clone fails for any
-reason, the launch automatically falls back to an archive of the local tree.
+reason, the launch automatically falls back to an archive of the local working tree,
+**including uncommitted changes**. The committed-only behavior applies to successful clones,
+not archive or configured-project copy transports.
 
 An **archive** is a gzip-compressed POSIX tar stream written to a temporary file and streamed
 to `PUT /v1/pods/:id/workspace/archive`. It contains tracked and untracked non-ignored files,
@@ -91,10 +94,12 @@ on the sandbox backend:
    the forwarding prompt; approve; `!git remote -v` inside the pod shows the https URL with no
    token, and `!cat .git/config` holds no token.
 3. **Declined forwarding** — answer `n`; expect an archive, and the pod still holds the tree.
-4. **Dirty repository archive** — edit a file, launch; expect `will be archived … (uncommitted
-   changes would be lost by a clone)` and `!git status` in the pod shows the same edit.
+4. **Dirty repository clone** — in a pushed, cloneable repository, stage a change, edit it
+   again, and add an untracked file. Launch; expect `will clone … (local uncommitted changes
+   are not copied)`. Inside the pod, `!git status` is clean, tracked content matches HEAD,
+   and the untracked file is absent. The host's staged, unstaged and untracked changes remain.
 5. **Non-git archive** — a plain directory of files; expect the files without a `.git`.
-6. **100+ MiB streaming archive** — a repository with a large untracked binary; watch the
+6. **100+ MiB streaming archive** — a repository without `origin`, with a large untracked binary; watch the
    `upload 25% …` lines; verify the file's checksum in the pod.
 7. **Interrupted upload** — Ctrl-C during upload; expect the pod deleted and no
    `pi-pod-seed-*.tar.gz` left in the temp directory.

package/man/pipod-config.5

@@ -1,4 +1,4 @@
-.TH "PIPOD\-CONFIG" "5" "October 2026" "0.1.10"
+.TH "PIPOD\-CONFIG" "5" "October 2026" "0.1.12"
 .SH "NAME"
 \fBpipod-config\fR \- pi pod configuration files
 .SH SYNOPSIS

package/man/pipod.1

@@ -1,4 +1,4 @@
-.TH "PIPOD" "1" "October 2026" "0.1.10"
+.TH "PIPOD" "1" "October 2026" "0.1.12"
 .SH "NAME"
 \fBpipod\fR \- run pi coding\-agent sessions in server\-managed pods
 .SH SYNOPSIS
@@ -90,9 +90,9 @@ bake script that is built into the pod image once, and Pi files\. Secrets are st
 the layers and reach pods as environment variables\. \fBpipod help layers\fP explains how they
 combine\.
 .P
-Every server layer has a local source of truth: a directory you edit with any editor, then
-upload with \fBpipod push\fP\|\. \fBpipod pull\fP writes the server's copy back, and \fBpipod diff\fP
-compares the two\.
+Every server layer, organization policy included, has a local source of truth: files you edit
+with any editor, then upload with \fBpipod push\fP\|\. \fBpipod pull\fP writes the server's copy back, and
+\fBpipod diff\fP compares the two\.
 .SH SETUP
 .P
 Setting pi pod up for yourself or an organization, in order\. A person has to do the steps
@@ -137,8 +137,20 @@ pipod push org
 .RE
 .P
 Values for secrets the whole organization shares: \fBpipod secrets set org <NAME>\fP (person)\.
-Organization policy (limits rather than defaults) is set in the web dashboard,
-\fB<server>/dashboard/\fP\|\.
+.P
+Organization policy (limits rather than defaults) needs the policy:write permission\. Its source
+is policy\.json beside the organization layer's files:
+.RS 2
+.nf
+pipod pull policy                # writes ~/\.pi\-pod/org/policy\.json
+                                 # edit it
+pipod diff policy
+pipod push policy
+.fi
+.RE
+.P
+To keep the organization's source in a repository instead, give each of these commands
+\fB\-\-dir <path>\fP\|\.
 .SS 5\. Your own defaults
 .P
 Your model and thinking level, your Pi settings, personal setup such as a git identity:
@@ -217,8 +229,8 @@ and the server refuses a literal key\.
 .P
 Organization policy holds limits rather than defaults: maximum idle and archive times,
 allowed providers, a required template, network rules, concurrency\. It clamps the merged
-result, and \fBpipod doctor\fP and \fBpipod \-\-dry\-run\fP report every clamp\. It is set in the web
-dashboard by someone with the policy:write permission\.
+result, and \fBpipod doctor\fP and \fBpipod \-\-dry\-run\fP report every clamp\. Someone with the
+policy:write permission changes it with \fBpipod push policy\fP or in the web dashboard\.
 .P
 Where each layer's source lives, and the commands that change it:
 .RS 2
@@ -229,6 +241,8 @@ user       ~/\.pi\-pod/config\.json and ~/\.pi/agent/
            pipod pull|diff|push user; pipod settings user set
 template   a project: \.pi\-pod/config\.json, init\.sh, bake\.sh, env, and \.pi/
            pipod pull|diff|push [template [<name>]]; pipod templates
+policy     ~/\.pi\-pod/org/policy\.json
+           pipod pull|diff|push policy                           (policy:write)
 .fi
 .RE
 .P
@@ -251,10 +265,13 @@ The launch uses the template named by \fB\-\-template\fP, or else the one pinned
 first launch offers to create a template from the project and pin it\.
 .P
 Workspace seeding: launching from a directory with no \.pi\-pod/config\.json seeds the new pod
-from that directory (its git repository root when inside one)\. A clean, pushed checkout whose
-remote tip matches HEAD is cloned at that exact commit; anything else (dirty trees, unpushed
-commits, private remotes without usable credentials, plain directories) is streamed in as a
-tar archive, without git\-ignored paths, node_modules, or \.pi\-pod/env\. Private\-remote
+from that directory (its git repository root when inside one)\. A pushed checkout whose
+remote tip matches HEAD is cloned at that exact committed HEAD, even with local uncommitted
+changes\. A successful clone does not copy staged, unstaged, or untracked changes and leaves
+the local checkout untouched\. When cloning is unavailable or fails (unpushed commits, private
+remotes without usable credentials, plain directories), the local working tree, including
+uncommitted changes, is streamed in as a tar archive, without git\-ignored paths, node_modules,
+or \.pi\-pod/env\. Private\-remote
 credentials are forwarded only after a prompt (\fB\-\-yes\fP approves it) and are never stored\.
 \fB\-\-dry\-run\fP prints the decision without prompting or creating a pod\. Forks, reused pods,
 \fB\-\-on\fP co\-location, and \fB\-\-no\-seed\fP never seed\. A project with a \.pi\-pod/config\.json gets its
@@ -459,7 +476,7 @@ A personal template sits above your user layer and an org\-wide one below it
 .SS pipod push
 .RS 2
 .nf
-Usage: pipod push [template [<name>] | user | org] [\-\-dir <path>]
+Usage: pipod push [template [<name>] | user | org | policy] [\-\-dir <path>]
                   [\-\-with\-secrets] [\-\-yes]
 
 Replace a server config bundle with its local source, whole\. The layer names
@@ -475,13 +492,16 @@ Layers and their local source:
                      models\.json, mcporter\.json, subagents\.json, agents/)
   org                ~/\.pi\-pod/org/: config\.json, init\.sh, bake\.sh, pi/…, and
                      an optional env file whose values become org secrets
+  policy             ~/\.pi\-pod/org/policy\.json: the organization policy, one
+                     JSON object of limits, checked by the server
 
 Inside a project the layer defaults to template; elsewhere it is required\.
 Provider credentials, hooks, mcpServers, and model credential values never
 leave this machine\.
 
 Options:
-  \-\-dir <path>     org only: read the org source from <path> instead
+  \-\-dir <path>     org and policy: read the org source directory from <path>
+                   instead
   \-\-with\-secrets   Also upload the layer's env values as secrets
   \-y, \-\-yes        Apply the replacement without the confirmation prompt
 .fi
@@ -493,7 +513,8 @@ confirm on, push declines unless \fB\-\-yes\fP is given\.
 .SS pipod pull
 .RS 2
 .nf
-Usage: pipod pull [template [<name>] | user | org] [\-\-dir <path>] [\-\-yes]
+Usage: pipod pull [template [<name>] | user | org | policy] [\-\-dir <path>]
+                  [\-\-yes]
 
 Write a server config bundle into its local source files (see
 `pipod push \-\-help` for the layer → directory table)\. A diff preview
@@ -511,21 +532,23 @@ Secrets stay on the server; their names are listed\. The user layer has no
 local script files, so user bundle scripts are shown but not written\.
 
 Options:
-  \-\-dir <path>   org only: write the org source to <path> instead
+  \-\-dir <path>   org and policy: write the org source directory at <path>
+                 instead
   \-y, \-\-yes      Apply the local changes without the confirmation prompt
 .fi
 .RE
 .SS pipod diff
 .RS 2
 .nf
-Usage: pipod diff [template [<name>] | user | org] [\-\-dir <path>]
+Usage: pipod diff [template [<name>] | user | org | policy] [\-\-dir <path>]
 
 Compare a config layer's local source with its server bundle (see
 `pipod push \-\-help` for the layer → directory table)\. Secrets compare by
 name only\. Exits 1 when they differ, 0 when they match\.
 
 Options:
-  \-\-dir <path>   org only: read the org source from <path> instead
+  \-\-dir <path>   org and policy: read the org source directory from <path>
+                 instead
 .fi
 .RE
 .SS pipod secrets

package/man/pipod.1.md

@@ -89,9 +89,9 @@ bake script that is built into the pod image once, and Pi files. Secrets are sto
 the layers and reach pods as environment variables. `pipod help layers` explains how they
 combine.
 
-Every server layer has a local source of truth: a directory you edit with any editor, then
-upload with `pipod push`. `pipod pull` writes the server's copy back, and `pipod diff`
-compares the two.
+Every server layer, organization policy included, has a local source of truth: files you edit
+with any editor, then upload with `pipod push`. `pipod pull` writes the server's copy back, and
+`pipod diff` compares the two.
 
 ## SETUP
 
@@ -139,8 +139,19 @@ pipod push org
 ```
 
 Values for secrets the whole organization shares: `pipod secrets set org <NAME>` (person).
-Organization policy (limits rather than defaults) is set in the web dashboard,
-`<server>/dashboard/`.
+
+Organization policy (limits rather than defaults) needs the policy:write permission. Its source
+is policy.json beside the organization layer's files:
+
+```
+pipod pull policy                # writes ~/.pi-pod/org/policy.json
+                                 # edit it
+pipod diff policy
+pipod push policy
+```
+
+To keep the organization's source in a repository instead, give each of these commands
+`--dir <path>`.
 
 ### 5. Your own defaults
 
@@ -207,8 +218,8 @@ project's .pi-pod/config.json. Within the layers:
 
 Organization policy holds limits rather than defaults: maximum idle and archive times,
 allowed providers, a required template, network rules, concurrency. It clamps the merged
-result, and `pipod doctor` and `pipod --dry-run` report every clamp. It is set in the web
-dashboard by someone with the policy:write permission.
+result, and `pipod doctor` and `pipod --dry-run` report every clamp. Someone with the
+policy:write permission changes it with `pipod push policy` or in the web dashboard.
 
 Where each layer's source lives, and the commands that change it:
 
@@ -219,6 +230,8 @@ user       ~/.pi-pod/config.json and ~/.pi/agent/
            pipod pull|diff|push user; pipod settings user set
 template   a project: .pi-pod/config.json, init.sh, bake.sh, env, and .pi/
            pipod pull|diff|push [template [<name>]]; pipod templates
+policy     ~/.pi-pod/org/policy.json
+           pipod pull|diff|push policy                           (policy:write)
 ```
 
 What belongs where: the organization layer holds what everyone needs (pod size, network
@@ -241,10 +254,13 @@ The launch uses the template named by `--template`, or else the one pinned in th
 first launch offers to create a template from the project and pin it.
 
 Workspace seeding: launching from a directory with no .pi-pod/config.json seeds the new pod
-from that directory (its git repository root when inside one). A clean, pushed checkout whose
-remote tip matches HEAD is cloned at that exact commit; anything else (dirty trees, unpushed
-commits, private remotes without usable credentials, plain directories) is streamed in as a
-tar archive, without git-ignored paths, node_modules, or .pi-pod/env. Private-remote
+from that directory (its git repository root when inside one). A pushed checkout whose
+remote tip matches HEAD is cloned at that exact committed HEAD, even with local uncommitted
+changes. A successful clone does not copy staged, unstaged, or untracked changes and leaves
+the local checkout untouched. When cloning is unavailable or fails (unpushed commits, private
+remotes without usable credentials, plain directories), the local working tree, including
+uncommitted changes, is streamed in as a tar archive, without git-ignored paths, node_modules,
+or .pi-pod/env. Private-remote
 credentials are forwarded only after a prompt (`--yes` approves it) and are never stored.
 `--dry-run` prints the decision without prompting or creating a pod. Forks, reused pods,
 `--on` co-location, and `--no-seed` never seed. A project with a .pi-pod/config.json gets its
@@ -451,7 +467,7 @@ A personal template sits above your user layer and an org-wide one below it
 ### pipod push
 
 ```
-Usage: pipod push [template [<name>] | user | org] [--dir <path>]
+Usage: pipod push [template [<name>] | user | org | policy] [--dir <path>]
                   [--with-secrets] [--yes]
 
 Replace a server config bundle with its local source, whole. The layer names
@@ -467,13 +483,16 @@ Layers and their local source:
                      models.json, mcporter.json, subagents.json, agents/)
   org                ~/.pi-pod/org/: config.json, init.sh, bake.sh, pi/…, and
                      an optional env file whose values become org secrets
+  policy             ~/.pi-pod/org/policy.json: the organization policy, one
+                     JSON object of limits, checked by the server
 
 Inside a project the layer defaults to template; elsewhere it is required.
 Provider credentials, hooks, mcpServers, and model credential values never
 leave this machine.
 
 Options:
-  --dir <path>     org only: read the org source from <path> instead
+  --dir <path>     org and policy: read the org source directory from <path>
+                   instead
   --with-secrets   Also upload the layer's env values as secrets
   -y, --yes        Apply the replacement without the confirmation prompt
 ```
@@ -485,7 +504,8 @@ confirm on, push declines unless `--yes` is given.
 ### pipod pull
 
 ```
-Usage: pipod pull [template [<name>] | user | org] [--dir <path>] [--yes]
+Usage: pipod pull [template [<name>] | user | org | policy] [--dir <path>]
+                  [--yes]
 
 Write a server config bundle into its local source files (see
 `pipod push --help` for the layer → directory table). A diff preview
@@ -503,21 +523,23 @@ Secrets stay on the server; their names are listed. The user layer has no
 local script files, so user bundle scripts are shown but not written.
 
 Options:
-  --dir <path>   org only: write the org source to <path> instead
+  --dir <path>   org and policy: write the org source directory at <path>
+                 instead
   -y, --yes      Apply the local changes without the confirmation prompt
 ```
 
 ### pipod diff
 
 ```
-Usage: pipod diff [template [<name>] | user | org] [--dir <path>]
+Usage: pipod diff [template [<name>] | user | org | policy] [--dir <path>]
 
 Compare a config layer's local source with its server bundle (see
 `pipod push --help` for the layer → directory table). Secrets compare by
 name only. Exits 1 when they differ, 0 when they match.
 
 Options:
-  --dir <path>   org only: read the org source from <path> instead
+  --dir <path>   org and policy: read the org source directory from <path>
+                 instead
 ```
 
 ### pipod secrets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipod/cli",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Run pi coding-agent sessions in server-managed pods",
   "type": "module",
   "license": "AGPL-3.0-only",