docs: add deploy scripts, skills, and pattern guides

Deploy scripts for webicached and webid (build, upload, restart).
AGENTS.md with releases.conf reference and variant tagging docs.
Installer archive pattern guide and version oddities reference.

AGENTS.md

@@ -370,3 +370,123 @@ Commit messages: `feat(<pkg>): add installer`, `fix(<pkg>): update install.sh`,
   `arch`, or `ext` explicitly in `releases.js`.
 - **Goreleaser archives**: Typically contain a bare binary at the archive root
   (not nested in a directory). Use `mv ./cmd "$pkg_src_cmd"`.
+
+---
+
+## Go Cache Daemon
+
+The Go pipeline (`cmd/webicached`) replaces the Node.js release-fetching code.
+It reads `releases.conf` files, fetches upstream release metadata, classifies
+build assets, and writes to `~/.cache/webi/legacy/` in the format the Node.js server expects.
+
+### Canonical Vocabulary
+
+The classifier MUST use exactly these strings. They match the production API.
+
+**OS**: `macos` (NOT `darwin`), `linux`, `windows`, `freebsd`, `openbsd`,
+`netbsd`, `dragonfly`, `aix`, `illumos`, `plan9`, `solaris`, `posix_2017`
+
+**Arch** — exact equivalences:
+- `amd64` (NOT `x86_64`), `x86` (NOT `i386`/`i686`/`386`)
+- `arm64` (NOT `aarch64`)
+- `armv7l` (NOT `armv7`), `armv6l` (NOT `armv6`)
+- `mipsle` (NOT `mipsel`), `mips64le` (NOT `mips64el`)
+
+**Arch** — compatibility downcasts:
+- `armhf` → `armv7l`, `armv7a` → `armv7l`, `armel` → `arm`
+
+**Arch** — other: `arm`, `ppc64le`, `ppc64`, `loong64`, `riscv64`, `s390x`,
+`mips`, `mips64`
+
+**Libc**: `none` (never empty), `gnu`, `musl`, `msvc`
+
+**Ext**: `tar.gz`, `tar.xz`, `zip`, `exe`, `7z`, `pkg`, `msi`
+(no leading dot; `exe` for bare binaries)
+
+### releases.conf
+
+Each package directory contains a `releases.conf` that tells the daemon where
+to fetch releases. Format is `key = value`, one per line. `#` comments and
+blank lines are ignored.
+
+#### Source types (mutually exclusive — pick one)
+
+```ini
+# GitHub binary releases (most common)
+github_releases = sharkdp/bat
+
+# GitHub source tarballs (with optional git fallback)
+github_sources = bnnanet/serviceman
+git_url = https://github.com/bnnanet/serviceman.git
+
+# Git tag enumeration (vim plugins, shell scripts — git_url alone)
+git_url = https://github.com/tpope/vim-commentary.git
+
+# Gitea (full URL required, or short form + base_url)
+gitea_releases = https://git.rootprojects.org/root/pathman
+
+# GitLab (defaults to gitlab.com)
+gitlab_releases = owner/repo
+
+# HashiCorp releases API
+hashicorp_product = terraform
+
+# Custom source (servicemandist, nodedist, zigdist, etc.)
+source = nodedist
+url = https://nodejs.org/download/release
+```
+
+#### Filtering, versioning, and platform
+
+```ini
+tag_prefix = bun-                    # monorepo: strip prefix from version
+version_prefixes = jq-               # strip from version string (space-separated)
+asset_filter = MinGit                # filename must contain this substring
+exclude = busybox -src- -docs-       # skip assets containing these (space-separated)
+os = posix_2017                      # restrict ALL versions to this OS (blanket)
+alias_of = rg                        # mirrors another package's releases
+```
+
+#### Design rules
+
+- `os` is a blanket tag on ALL versions. Only use for packages that are always
+  POSIX-only. For version-dependent OS tagging, use a custom `TagVariants` in
+  `internal/releases/{pkg}/variants.go`.
+- `git_url` can be primary (gittag source when it's the only key) or secondary
+  fallback alongside `github_sources`/`gitea_sources`.
+- Full URL forms accepted for github/gitea/gitlab (e.g.
+  `github_releases = https://github.com/sharkdp/bat`).
+
+### Testing
+
+Test tools: `cmd/e2etest` (pipeline comparison), `cmd/comparecache` (cache diff),
+`cmd/inspect` (single-package debug). Run each with `--help` for usage.
+
+### Classifier vs Per-Package Tagger
+
+The general classifier (`internal/classify/`) handles patterns common across
+many projects. It MUST NOT contain one-off logic for a single package.
+
+Per-package taggers (`internal/releases/{pkg}/variants.go`) handle
+project-specific knowledge. Read the existing taggers for conventions.
+
+MUST: Derive arch/OS from concrete evidence — not blanket defaults.
+MUST: New general classifier patterns must apply to 2-3+ packages.
+
+### Deploying
+
+```sh
+./scripts/deploy-webicached.sh beta.webi.sh
+./scripts/deploy-webicached.sh next.webi.sh
+```
+
+First-time setup on a new host uses `serviceman`:
+
+```sh
+serviceman add --name webicached \
+  --workdir ~/srv/webid/installers/ -- \
+  ~/bin/webicached \
+    --envfile ~/srv/webid/.env.secret \
+    --conf ~/srv/webid/installers/ \
+    --raw ~/.cache/webi/raw
+```