TASK-0013: document the dev plugin loop

.gitignore

@@ -2,5 +2,6 @@ system-go/lattice-plugin-example
 system-go/system-go
 ui/node_modules/
 ui/dist/
+.lattice-dev/
 *.tar.gz
 *.wasm

Makefile

@@ -0,0 +1,28 @@
+override DEV_DIR := .lattice-dev
+DEV_HANDLE ?= $(shell id -un | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9-' '-' | sed 's/^-//;s/-$$//')
+DEV_PUBLISHER ?= dev.$(DEV_HANDLE)
+DEVPLUGIN ?= go run github.com/LatticeNet/lattice-server/tools/devplugin@f98fe94e31da86296c7aa9b5bdb97d6e1f7a51c5
+override DEV_SEED := $(DEV_DIR)/publisher.seed
+override DEV_TRUST := $(DEV_DIR)/plugin-trust.local.json
+override DEV_BUNDLE := $(DEV_DIR)/reference-plugin.tar.gz
+override DEV_MANIFEST := $(DEV_DIR)/manifest.dev.json
+
+.PHONY: dev-key dev-bundle dev-plugin
+
+dev-key:
+	$(DEVPLUGIN) keygen -publisher "$(DEV_PUBLISHER)" -seed "$(DEV_SEED)" -trust "$(DEV_TRUST)"
+
+dev-bundle:
+	mkdir -p "$(DEV_DIR)"
+	set -eu; \
+	stage=$$(mktemp -d "$(DEV_DIR)/bundle.XXXXXX"); \
+	trap 'rm -rf "$$stage"' EXIT; \
+	mkdir -p "$$stage/bin/linux-amd64" "$$stage/bin/linux-arm64" "$$stage/ui"; \
+	(cd system-go && GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -buildvcs=false -o "../$$stage/bin/linux-amd64/plugin" .); \
+	(cd system-go && GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -trimpath -buildvcs=false -o "../$$stage/bin/linux-arm64/plugin" .); \
+	(cd ui && npm run build); \
+	cp -R ui/dist/. "$$stage/ui"; \
+	(cd tools/pluginpack && go run ./cmd/pluginpack -source "../../$$stage" -output "../../$(DEV_BUNDLE)")
+
+dev-plugin: dev-bundle
+	$(DEVPLUGIN) sign -publisher "$(DEV_PUBLISHER)" -seed "$(DEV_SEED)" -manifest manifest.json -artifact "$(DEV_BUNDLE)" -output "$(DEV_MANIFEST)"

README.md

@@ -83,21 +83,70 @@ Run Go tests within each Go module:
 Build a bundle workspace and package it deterministically:
 
 ```bash
-tmpdir="$(mktemp -d)"
+mkdir -p .lattice-dev
+tmpdir="$(mktemp -d .lattice-dev/manual.XXXXXX)"
+trap 'rm -rf "$tmpdir"' EXIT
 mkdir -p "$tmpdir/bundle/bin/linux-amd64" "$tmpdir/bundle/bin/linux-arm64" "$tmpdir/bundle/ui"
-(cd system-go && GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -buildvcs=false -o "$tmpdir/bundle/bin/linux-amd64/plugin" .)
-(cd system-go && GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -trimpath -buildvcs=false -o "$tmpdir/bundle/bin/linux-arm64/plugin" .)
+(cd system-go && GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -buildvcs=false -o "../$tmpdir/bundle/bin/linux-amd64/plugin" .)
+(cd system-go && GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -trimpath -buildvcs=false -o "../$tmpdir/bundle/bin/linux-arm64/plugin" .)
 cp -R ui/dist/. "$tmpdir/bundle/ui"
-(cd tools/pluginpack && go run ./cmd/pluginpack -source "$tmpdir/bundle" -output "$tmpdir/reference-plugin.tar.gz")
+(cd tools/pluginpack && go run ./cmd/pluginpack -source "../../$tmpdir/bundle" -output "../../.lattice-dev/reference-plugin.tar.gz")
 ```
 
 `pluginpack` normalizes archive paths, rejects unsafe names and symlinks, stamps
 tar entries at the Unix epoch, zeros uid/gid, and uses mode `0700` for
 directories and runtime binaries (`bin/**/plugin`) with `0600` for other files.
+The local Makefile and examples publish archives under `.lattice-dev/` so local
+packaging cannot overwrite the checked-in `manifest.json`.
 Release builds pin Node.js 22 and Go 1.26.4. Both toolchains are part of the
 signed byte contract: changing either can alter the bundled UI or runtime even
 when the source tree is unchanged.
 
+## Local Development With A Dev Key
+
+Local development uses a per-developer publisher named `dev.<handle>` and the
+same signature verification path as production. It does not use
+`allow_unsigned_host_risk`.
+
+Generate a local seed and trust file:
+
+```bash
+make dev-key
+```
+
+This writes `.lattice-dev/publisher.seed` and
+`.lattice-dev/plugin-trust.local.json`. The entire `.lattice-dev/` directory is
+gitignored. Do not copy these files into a production trust file, CI job, or
+release process. The Makefile intentionally fixes generated seed, trust, bundle,
+and dev manifest paths under `.lattice-dev/`; `DEV_HANDLE`, `DEV_PUBLISHER`, and
+`DEVPLUGIN` are the supported overrides.
+
+Build a local bundle and dev manifest:
+
+```bash
+make dev-plugin
+```
+
+The target packages `.lattice-dev/reference-plugin.tar.gz` and writes
+`.lattice-dev/manifest.dev.json` with publisher `dev.<handle>`, an artifact
+digest matching the local bundle, and a dev signature. The checked-in
+`manifest.json` stays unchanged.
+
+If the server tooling is checked out beside this plugin repo, use the local
+branch instead of the published tool while developing the tooling itself:
+
+```bash
+make DEVPLUGIN='go run ../lattice-server/tools/devplugin' dev-plugin
+```
+
+Without that override, the Makefile runs the tool from the exact reviewed server
+commit pinned in `DEVPLUGIN`.
+
+Point a local server at `.lattice-dev/plugin-trust.local.json` when you want it
+to load the dev-signed manifest. A server whose trust file does not list your
+`dev.<handle>` publisher rejects that bundle through the ordinary trusted
+publisher check.
+
 ## Signing
 
 The checked-in manifest represents the published alpha artifact and therefore