Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
docs: the re-clone remedy did not move the rewritten tag (#98)
Matthew Kissingere2a41ed039be
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4609062a..8569dd1c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -3,6 +3,31 @@Changes to `@kiln/engine`. Source and installable packages are distributed throughGitHub. The package is not published on the npm registry.+## The documented way to convert an old clone did not work — 2026-09-12++- The 2026-09-10 rewrite moved `refs/tags/oss-2026-09-05` as well as `main`, and a tag+ is the one ref `git fetch` will not update on its own. So the README's remedy+ — `git fetch origin && git reset --hard origin/main` — left the old tag in place,+ holding every removed file reachable. Measured on the clone this was found in:+ `.git` at 228 MB where a fresh clone is 26 MB, with identical content.+- Reproduced by running the documented commands verbatim in a throwaway copy. The two+ obvious next guesses are not merely ineffective, they are **refused**: plain+ `git fetch --tags` and even `--prune-tags` both report `would clobber existing tag`,+ so a reader has no route to the answer without already knowing `--force`.+- The instructions now force the tag and then reclaim. Verified end to end on the real+ stale clone: 228 MB to 23 MB, `fsck` clean, `HEAD` and the working tree hash+ byte-identical before and after. The plan document already recorded that "the tag was+ the whole rewrite" for the *push* side; this is the same fact on the clone side, which+ is the side a reader is on.+- `scripts/reliability.test.mjs` pins it, and asserts the **absence** of the broken form+ as well as the presence of the working one — the short version is what a later+ simplification reaches for.+- Clone figures re-measured: 60 MB full and 49 MB with `--filter=blob:none`, where the+ README said 52 MB and 48 MB. `.git` grew from 18 MB to 26 MB when the runtime bundles+ were re-added after the rewrite; the checkout is unchanged at 34 MB. The timing claims+ are removed rather than restated — they are network-bound and cannot be honestly+ re-verified from a different link.+## Skill bytes are canonical, and the SEP-2640 record is corrected — 2026-09-12- Re-read SEP-2640 from the spec text on its PR branch and the working group's owndiff --git a/README.md b/README.mdindex d1b1eefb..8f523585 100644--- a/README.md+++ b/README.md@@ -80,19 +80,35 @@ bun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.pngfile contents on the server, fetching them only if you ask for an old revision.A plain `git clone` also works and gives you the whole history up front.-History was rewritten on 2026-09-10 to drop 288 MB of gallery renders and launch-video that no tool reads, taking a clone from 440 MB and 79 seconds to 52 MB and-8 seconds, or 48 MB with `--filter=blob:none`. Every commit survived and the tree-is unchanged apart from those files, but every commit hash changed, so a clone-made before that date cannot fast-forward. Re-clone, or discard local history-with `git fetch origin && git reset --hard origin/main`. The gallery images are-served from `assets.kilnstudio.tools`; the 83 poster receipts that attest their-bytes stayed in `examples/renders/`.-This writes a GLB and a six-view image of an existing program. It makes no model call.Rendering uses the CPU unless a compatible local GPU service is available.Use `--render cpu` to select the CPU explicitly.+History was rewritten on 2026-09-10 to drop 288 MB of gallery renders and launch+video that no tool reads, taking a clone from 440 MB to 60 MB, or 49 MB with+`--filter=blob:none`; measured 2026-09-12. Every commit survived and the tree is+unchanged apart from those files, but every commit hash changed, so a clone made+before that date cannot fast-forward.++Re-cloning is simplest. To convert a clone you already have, move the **tag** as+well as the branch:++```sh+git fetch --tags --force origin+git reset --hard origin/main+git reflog expire --expire=now --all+git gc --prune=now+```++`--force` is the load-bearing flag. `oss-2026-09-05` was rewritten too, and git+will not move a tag that already exists without it: plain `git fetch --tags`, and+even `--prune-tags`, both report `would clobber existing tag` and leave the old+one in place, holding every removed file reachable. Omit it and `.git` stays at+228 MB where a fresh clone is 26 MB; run it and the same clone packs to 23 MB.++The gallery images are served from `assets.kilnstudio.tools`; the 83 poster+receipts that attest their bytes stayed in `examples/renders/`.+## Connect your agentThe [agent reading guide](site/public/llms.txt) links to setup, tool schemas and thediff --git a/docs/plans/repo-size-and-r2-migration-2026-09-10.md b/docs/plans/repo-size-and-r2-migration-2026-09-10.mdindex a1e49bec..ff04a05a 100644--- a/docs/plans/repo-size-and-r2-migration-2026-09-10.md+++ b/docs/plans/repo-size-and-r2-migration-2026-09-10.md@@ -2065,3 +2065,73 @@ supplied by an arbitrary connected server -- but if archives ever come back to Mthe SEP names the conditions: no symlinks, no non-regular entries, a declareduncompressed size, never the sole retrieval form, and unpacking to exactly the fileset the entry enumerates.+++## Phase 15 -- What an audit of the audit found++Opened 2026-09-12, after Phase 14 closed with every row done or blocked upstream. The+starting question was whether "nothing open" was true, and the way to answer it was to+measure the repository rather than re-read the record. Every gate passes offline --+`check:toolchain`, `check:skills`, `typecheck`, `lint` over 481 files, 1858 pass / 2+skip / 0 fail across 215 files, render-service 37 pass, coverage 95.39% functions /+92.59% lines with 46 functions and 222 lines of slack. `bun outdated` across all three+manifests returns only the upstream-blocked `ai` 7 family plus one `webgpu` patch.++So the ledger was accurate. Four things it does not cover came out of measuring anyway,+and three of them are the same shape: a claim this repository publishes that nobody had+re-measured since the day it was written.++| ID | Task | State |+| --- | --- | --- |+| 15.1 | The README's remedy for converting a pre-rewrite clone does not work | **Done 2026-09-12.** See below |+| 15.2 | Three CI jobs report on every PR and block nothing | Queued; the repository half and the GitHub setting |+| 15.3 | The documented offline gate does not run render-service's 37 tests, or `check:skills` | Queued |+| 15.4 | `version` has been `0.6.0` for 21 shipped changes, and the tarball is named from it | Queued; owner chose to bump per shipped change |++### 15.1 -- the tag is the whole rewrite, on the clone side too++Phase 3 already learned this in one direction. `git push --force origin main` looked+complete while a fresh clone still measured 57 MiB, because `refs/tags/oss-2026-09-05`+still pointed at the original `d941f15` and held every removed blob reachable; pushing+the tag took the clone from 92 MB to 52 MB, and the note written then says *"anyone+repeating this work should push every ref."*++The same fact applies to a reader converting an old clone, and the README did not say+so. Its remedy was `git fetch origin && git reset --hard origin/main`, which moves the+branch and leaves the tag. **This working copy was the evidence**: `.git` at 228 MB,+`HEAD` in sync with `origin/main`, the local tag still at `d941f15` with 66 removed+PNGs, against a fresh clone's 26 MB of identical content.++Reproduced in a throwaway copy by running the documented commands verbatim -- 59 MB+afterwards, and only because a `git gc` the README never mentions was added; without it,+228 MB. The two obvious next guesses are worse than ineffective, they are **refused**:++| Command | Result |+| --- | --- |+| `git fetch origin && git reset --hard origin/main` (documented) | tag unchanged at `d941f15` |+| `git fetch --tags origin` | `! [rejected] ... would clobber existing tag` |+| `git fetch --prune-tags --tags origin` | same rejection |+| `git fetch --tags --force origin` | `t [tag update]`, then 23 MB after `gc --prune=now` |++A reader therefore cannot discover `--force` by trying the obvious things first, which+is what makes this a documentation defect rather than a shortcut anybody would find.++Fixed, pinned in `scripts/reliability.test.mjs`, and verified the way the ratchet's own+tests are: the assertion fails on the old README text for the stated reason before it+passes on the new one. It asserts the **absence** of the broken form as well as the+presence of the working one, because the short version is the one a later simplification+reaches for.++Applied to this clone as well, backup first: a `git bundle` of the pre-rewrite lineage+(`dd9d5f7`, 177 commits, 235 MB) was written outside the tree and *verified by restoring+it* -- 119 removed files present at the tip, and all 83 posters recovered with sha256+matching the `imageHash` in their `examples/renders/*.json` receipts, which is invariant+I1 from Phase 1 run against the backup instead of the bucket. Only then the tag was+forced and the objects pruned: 228 MB to 23 MB, `fsck` clean, `HEAD` and tree hash+byte-identical.++**The clone figures had also drifted**, which is the second instance of the same shape.+60 MB full and 49 MB filtered, where the README said 52 MB and 48 MB: `.git` grew 18 MB+to 26 MB when the runtime bundles were re-added after the rewrite, and the checkout is+unchanged at 34 MB. The timing claims came out rather than being restated, because they+are network-bound and cannot be honestly re-measured from a different link.diff --git a/scripts/reliability.test.mjs b/scripts/reliability.test.mjsindex f51cf023..ad0cce25 100644--- a/scripts/reliability.test.mjs+++ b/scripts/reliability.test.mjs@@ -154,6 +154,27 @@ describe('repository reliability contracts', () => {expect(workflow).toContain('Report the native dependency inventory');});+ // The 2026-09-10 rewrite moved `refs/tags/oss-2026-09-05` as well as `main`, and a+ // tag is the one ref `git fetch` will not update on its own. That makes the stale+ // tag, not the branch, what keeps 288 MB of removed files reachable in an old clone+ // -- so the documented remedy has to force it. This is not hypothetical tidying: the+ // instructions here really did omit it, and a clone that had run them still measured+ // 228 MB against a fresh clone's 26 MB.+ //+ // Asserting the absence matters more than asserting the presence. The broken form is+ // the shorter, more obvious one, so it is what a later edit reaches for.+ test('the re-clone remedy moves the rewritten tag, not just the branch', async () => {+ const readme = await readText('README.md');++ expect(readme).toContain('git fetch --tags --force origin');+ // Both near-misses are *refused* by git rather than silently ineffective, which is+ // why a reader cannot discover `--force` by trying the obvious things first.+ expect(readme).not.toContain('git fetch origin && git reset --hard origin/main');+ expect(readme).toContain('oss-2026-09-05');+ // Forcing the tag frees nothing until the objects it pinned are actually dropped.+ expect(readme).toContain('git gc --prune=now');+ });+test('standalone agent context stays concise and names the safety-critical paths', async () => {const agents = await readText('AGENTS.md');