Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 35 additions & 5 deletions .claude/skills/sc-cli-reference/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,11 @@ cd apps/desktop && npm run tauri dev # native desktop development app
cd apps/desktop && npm run tauri build -- --bundles app # validated macOS production bundle
cargo run --bin sc -- demo --agents 4 # parallel-agent demo
cargo run --bin sc -- demo --agents 6 --budget-mb 4 --spill # exercise eviction
cargo run --bin sc -- demo --agents 4 --checkout # also materialize each worktree to a session
# temp dir (the one disk-writing path), then clean up
cargo run --bin sc -- import --repo <path> # import a Git repo's HEAD
bash demo/run_demo.sh # independent zero-residue proof
cargo run --bin sc -- keygen # v2 identity: one seed derives BOTH an X25519
cargo run --bin sc -- keygen [--out <file>] # (default ~/.sc/identity; 0600 on unix only) v2 identity: one seed derives BOTH an X25519
# encryption key and an Ed25519 signing key (P22);
# a pre-P22 v1 (scl-sk-) identity still parses and
# still encrypts, but cannot sign
Expand Down Expand Up @@ -77,7 +79,9 @@ cargo run --bin sc -- resolve --ours|--theirs <path>... [--identity <key>]
# merge/pick/rebase conflict record (P23)
cargo run --bin sc -- scan # preview the commit-time secret scan
cargo run --bin sc -- clone <src> <dst> # copy a repo (objects + refs)
cargo run --bin sc -- protect <prefix> --to <recipient> # encrypt matching paths (P7)
cargo run --bin sc -- protect <prefix> --to <recipient> # encrypt matching paths (P7); sealing
# is randomized since P33 (ADR-0043)
cargo run --bin sc -- protect [--list] [--json] # list the protection rules (no prefix = list)
cargo run --bin sc -- grant <prefix> --to <recipient> --identity <key> # path-protection grant
cargo run --bin sc -- revoke <prefix> --recipient-id <id> # path-protection revoke;
# tombstone-durable across merges of pre-revoke
Expand All @@ -102,8 +106,13 @@ cargo run --bin sc -- run [--secrets-fd N] -- <cmd> [args…] # inject decrypt
cargo run --bin sc -- gc # pack reachable objects + prune unreachable
cargo run --bin sc -- gc --prune-expire 7d # custom grace window
cargo run --bin sc -- export --to <git-repo> # write current branch history to Git
cargo run --bin sc -- export --to <git-repo> --ref <ref> # update this Git ref instead of
# refs/heads/<current-branch>
cargo run --bin sc -- export --to <git-repo> --include-encrypted # allow protected ciphertext
bash demo/run_repo_demo.sh # end-to-end persistent repo proof
bash demo/run_remote_demo.sh # local-path remote round trip (P6): clone, then
# fetch+merge and push between two local repos
cargo run --bin sc -- remote list # name, URL and kind ([sc] / [git]) of each remote
cargo run --bin sc -- remote add <name> <git-path> --git # register a git-backed remote
cargo run --bin sc -- fetch <git-remote> # import git history -> remote-tracking ref
cargo run --bin sc -- push <git-remote> [--include-encrypted] # export sc history -> git ref (ff-only)
Expand Down Expand Up @@ -141,8 +150,9 @@ bash demo/run_randomized_demo.sh # randomized protected-enc
# rewrap UPGRADE and pre-P33 dual-read are unit-
# test-pinned, since the current binary can no
# longer write a convergent blob)
cargo run --bin sc -- work --agents 3 -- <cmd> # fork agent workspaces, run <cmd> in each,
# harvest changed ones to work-<i> branches
cargo run --bin sc -- work --agents 3 [--name <base>] -- <cmd> # fork agent workspaces, run
# <cmd> in each, harvest changed ones to
# <base>-<i> branches (default base `work`)
# (--with-secrets --identity <key> injects
# decrypted secrets into each agent env)
bash demo/run_work_demo.sh # parallel-agents round-trip proof
Expand All @@ -156,7 +166,8 @@ cargo run --bin sc -- ws harvest [--into <branch>] [--identity <key>] # probe
# every live workspace onto the landing branch
# (default the session's base branch, which must
# be checked out); clean lands cumulatively,
# conflicts fall back to work-<i>
# conflicts fall back to work-<i> (always `work`;
# `--name` is `sc work` only)
cargo run --bin sc -- ws abandon [<i>] # drop one workspace or the whole session
bash demo/run_ws_demo.sh # multi-invocation session + auto-merge proof (P20)
cargo run --bin sc -- cherry-pick <ref> [--identity <key>] # replay one commit onto the
Expand Down Expand Up @@ -333,6 +344,21 @@ cargo run --bin sc -- serve token list [--json] # list labels, scopes, expiry
cargo run --bin sc -- clone sc+http://host[:port]/repo <dst> # clone over sc+http:// (P26;
# port defaults to 8730); sc remote add/fetch/push
# accept the same sc+http:// URL form
cargo run --bin sc -- remote add <name> sc+wal://<dir> # bucket WAL remote on a local
# directory (P36, ADR-0046); `clone` takes the URL
# directly, `fetch`/`push` use the remote's name
cargo run --bin sc -- remote add <name> sc+s3://<bucket>/<prefix> # same, on an S3-compatible
# store; a malformed URL (e.g. no bucket) is rejected
# at `remote add` time. Public content is plaintext at
# rest (the bucket ACL is the perimeter; sealed
# content stays ciphertext); `clone --filter` is
# refused; signatures, transcripts and drop
# tombstones travel like on any native remote (#229)
cargo run --bin sc -- serve --http <addr> <home> --store sc+wal://<dir>|sc+s3://<bucket>/<prefix>
# serve a bucket remote over sc+http(s):// (P36c):
# all content lives in the bucket (instance is
# disposable); <home> still needs `.sc/` for tokens,
# the TLS identity and scratch space
bash demo/run_http_remote_demo.sh # sc-native HTTP transport proof (P26): real
# loopback TCP (no shim, unlike ssh://), clone +
# push + fetch over sc+http://, a signed ~1 MiB
Expand Down Expand Up @@ -378,6 +404,10 @@ bash demo/run_partial_clone_demo.sh # partial clone proof (P27): sc cl
# edit AND byte-identical docs/lib); sc backfill
# docs/ shrinks the gap count; sc gc succeeds and
# preserves everything; run twice
bash demo/run_limits_demo.sh # listener-limits proof (P31): --max-connections
# busy shed and slot reuse; --timeout and
# --max-pack-size are accepted (timeout expiry
# itself is unit-tested, not shown here)
bash demo/run_http_auth_demo.sh # sc+http access-control proof (P29): a no-token
# clone is rejected with an authentication error,
# an ro-token clone reads but its push is rejected
Expand Down
18 changes: 16 additions & 2 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -356,7 +356,8 @@ phases but the shape is stable:
`PICK_HEAD`, `REBASE_STATE`, and their `*_DECIDED_ROOT` records, plus
`CONFLICT_PLAINTEXT` / `CONFLICT_SIDECARS` listing what a stopped operation
wrote into the working tree — an interrupted merge/pick/rebase resumes or
aborts cleanly from these.
aborts cleanly from these. `sparse-widen` records the files a widening
`sparse set` is laying out while an operation is stopped (P24, #224).
- The `sc+https://` client's pin file is user-level, not part of `.sc/`
(`$SC_HTTPS_KNOWN_HOSTS`, else `$XDG_CONFIG_HOME/sc/known_hosts`, else
`~/.config/sc/known_hosts`; managed with `sc tls`).
Expand All @@ -369,6 +370,11 @@ branch ref. `switch` materializes the target branch tip into the working tree,
removing tracked files that are absent from the target, and refuses the
operation if tracked files are modified or deleted (to prevent data loss). New,
untracked files are left in place. `status` diffs the working tree against HEAD.
The write-out paths (switch, merge, rebase, `sparse set`, clone, `ws fork`,
private and conflict write-outs) apply the recorded file mode through one
helper, so an executable file stays executable on unix and a stale execute bit
is cleared on a plain file (#242). `sc resolve` after the user deleted a
conflicted file does not use it yet (#243).

### Mode-scoped disk invariant

Expand Down Expand Up @@ -845,7 +851,10 @@ workspace's never-materialized paths as deletions.

A clean merge/pick/rebase change to an out-of-sparse path lands in the CAS
without materializing; a CONFLICT there refuses up front with a "run `sc
sparse set` to include it" hint. Sparse is CHECKOUT-only — every object
sparse set` to include it" hint. While the operation is stopped, `sparse set`
accepts only a strict widen (the new spec covers the old one): it lays out the
newly in-view files from the stop's decided root, leaves protected ones absent,
and the interrupted write is journaled in `.sc/sparse-widen` (#224). Sparse is CHECKOUT-only — every object
stays in the CAS regardless of the spec, so `sc gc`'s reachability walk is
unaffected; not fetching out-of-prefix objects at all is deferred to P27.
See ADR-0034.
Expand Down Expand Up @@ -1004,6 +1013,11 @@ opening, connection-fatal on trip since a mid-stream abort desyncs the frame
stream), and `--max-pack-size` (default 16 GiB, floor = the max object
size, 256 MiB by default; lives in the shared `WirePolicy`, so it applies to both
`--http` and `--stdio`; a counted mid-stream abort replies `EC_TOO_LARGE`).
Later additions to the same policy: `--max-object-size` (operator-configurable
per-object cap, #213) and `--max-conn-bytes`, a per-connection write budget on
both transports that counts every `PutObject` and each `PutPack`'s larger of
spool and decoded bytes, replies `ConnectionBudgetExceeded` and closes (#233,
no `PROTOCOL_VERSION` change; see the ADR-0039 additions).

The read-only pre-drain is capped at 8 MiB (`RO_DRAIN_CAP`), and the accept
loop gained a hardcoded Go-`net/http`-shaped exponential backoff around fd
Expand Down
Loading
Loading