Adding tools to Tiny

Tiny uses /home/loca/dev/tiny/tools.json as its sole tool registry. The application dock and generated wiki index must consume that same file; do not add a second hand-maintained catalog. The current application deployment is planned, not yet verified: see Current state.

Preserve provenance before development

The Terracraft import is frozen at 243f3e39a06516d4d92324eb00d0e277978c9281. Its original location is dv@0rk.de:/home/dv/dev/terracraft; that original directory was not made into a Git repository. A separate export copy was committed, transferred, pushed into /home/loca/dev/tiny-terracraft.git, and cloned into sources/terracraft.

Treat the imported clone and bare repository as rollback anchors. Do not edit or commit inside the imported clone, rewrite its history, or develop in the original remote directory. A source change belongs in a separate working copy. For example, choose a new, nonexistent working directory:

git clone --no-hardlinks /home/loca/dev/tiny-terracraft.git /tmp/terracraft-work
git -C /tmp/terracraft-work switch -c local-development 243f3e39a06516d4d92324eb00d0e277978c9281
python3 -m http.server 55333 --bind 127.0.0.1 --directory /tmp/terracraft-work

Open http://127.0.0.1:55333/ on the machine running the server. Edit /tmp/terracraft-work/index.html or its assets and reload the browser. This is the actual source development loop: plain static serving, not a bundler or a fictitious upstream npm command. The original dependency imports still require esm.sh access. Work intended for retention should use an explicitly chosen persistent working directory rather than /tmp.

Record intentional changes in that separate working repository. Integration of a new source revision is a deliberate provenance update with a new frozen commit and rollback record; do not silently replace the old import. The current Tiny mission only permits path rebasing of pinned dependency imports in a generated mounted copy, not unrelated behavior fixes.

flowchart LR
  Original[Unchanged original] --> Export[Committed export]
  Export --> Frozen[Immutable imported clone]
  Frozen --> Working[Separate development copy]
  Frozen --> Mounted[Generated mounted copy]
  Mounted --> Dist[Static app artifact]

Add a registry entry

Use the existing schema without introducing a second version or alias:

{
  "slug": "terracraft",
  "name": "Terracraft",
  "description": "Minecraft glazed-terracotta block-grid pattern planner",
  "path": "/t/terracraft/",
  "wiki": "https://wiki.tiny.loca.zone/terracraft",
  "source": "sources/terracraft",
  "origin": "dv@0rk.de:/home/dv/dev/terracraft",
  "origin_commit": "243f3e39a06516d4d92324eb00d0e277978c9281"
}

Place each object in the top-level tools array. Select a unique slug, mounted path, and public quickstart URL. source is relative to the Tiny project; origin records where the source came from, not a public download URL; origin_commit records the full frozen source SHA, not the Tiny shell commit.

Documentation first

1. Inspect the real source and write content/<slug>.md in /home/loca/dev/wikis/tiny. Include purpose, local run steps, dependency versions, file map, controls, limitations, and provenance.
2. Distinguish README claims, inspected implementation, and browser-proven behavior. Do not describe a planned deployment as live.
3. From /home/loca/dev/tiny, run node scripts/wiki.mjs. This writes only /home/loca/dev/wikis/tiny/content/index.md; it is not a Quartz or application build. Never hand-edit that generated index.
4. Documentation-first, not a hard gate: wiki publication and application implementation proceed independently. Never describe a planned deployment as live; public HTTPS for either host is recorded as awaiting Gatekeeper ingress until it really responds.

Integrate and verify

The target app build command is npm run build, with static output in dist. It must mount copies, retain tool behavior, and produce dock entries from the registry. Do not assume that command exists until the application implementation has landed. For Terracraft, local vendoring of Preact 10.19.2 and HTM 3.1.1 is a pinned-import path change in generated output; the frozen clone remains untouched.

Before publishing, inspect passive ownership and /home/loca/dev/wikis/.publisher-hardening/active.json. An unresolved foreign publisher transaction or writer is a blocker, not permission to restore shared state. All builds must run at nice 10 under /home/loca/.flowmaster-d181/heavy.lock; the wiki publisher additionally owns .global-build.lock.

The operator uses /home/loca/dev/wikis/build.sh tiny --check-only and then /home/loca/dev/wikis/build.sh tiny, with umask 022, only after ownership and content preflight pass. Never edit shared Quartz or bypass this publisher. Capture any existing current target before publication, then prove emitted permissions, anonymous HTTP content, links, and browser rendering. A first publication has no previous Tiny release to restore.

Build and verify the application independently of wiki publication: direct navigation to each registry path, dock switching, source assets, tool interactions, export output, and absence of runtime CDN requests. The shell build is pinned Tailwind 4 + daisyUI 5 with a committed lockfile; Terracraft mounts use locally vendored Preact 10.19.2 / HTM 3.1.1 via an import map. Public vhost and certificate application is Gatekeeper-only; local proof is recorded as local, never as public. Update Current state with actual results rather than inferring success from a build exit code. If a provider responds with 429, stop and report BLOCKED without retrying.