docs: add Veilid upgrade skill

.claude/skills/veilid-upgrade/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: veilid-upgrade
+description: Upgrade Veilid across the OpenArchive Rust dependency chain. Use when asked to upgrade Veilid, bump Veilid, move to a new Veilid version, refresh veilid-core or veilid-tools tags, or run the cross-repo Veilid release cascade for veilid-iroh-blobs, save-dweb-backend, and save-rust.
+---
+
+# Veilid Upgrade
+
+Upgrade Veilid one repository at a time, in dependency order:
+
+1. `../veilid-iroh-blobs`
+2. `../save-dweb-backend`
+3. current `save-rust`
+
+Read `references/dependency-map.md` before editing. It contains the repo-specific pins, git URLs, and verification commands. Treat it as a map, not as a substitute for inspecting the current files.
+
+## Ground Rules
+
+- Locate dependency entries by package key or `rg`, never by hardcoded line number.
+- Keep fork-origin migration separate from a Veilid version bump unless the user explicitly asks to combine them.
+- Pause after each PR is opened and ask the human to review and merge before tagging and continuing downstream.
+- Verify each repo's default branch, origin, and push/tag permissions before creating PRs or tags.
+- Default to a patch version bump for routine dependency-only upgrades; use a minor bump only when the changelog or API impact warrants it.
+
+## One-Time Fork Migration
+
+The chain historically depended on personal upstream forks:
+
+- `RangerMauve/veilid-iroh-blobs`
+- `tripledoublev/iroh`
+
+OpenArchive forks now exist and should be the long-term dependency sources:
+
+- `OpenArchive/veilid-iroh-blobs`
+- `OpenArchive/iroh`
+
+Repoint references in standalone PRs before or after a Veilid upgrade. Do not mix that origin migration into the Veilid bump unless the user asks.
+
+Until a repo's migration PR is merged, operate against the current upstreams listed in that repo's manifest.
+
+## Step 0: Verify The Target Veilid Tag
+
+Discover the target tag live. Prefer machine-readable sources over GitLab HTML pages:
+
+```bash
+git ls-remote --tags https://gitlab.com/veilid/veilid.git
+curl -fsS 'https://gitlab.com/api/v4/projects/veilid%2Fveilid/repository/tags?per_page=10'
+curl -fsS https://gitlab.com/veilid/veilid/-/raw/main/CHANGELOG.md
+```
+
+Record the target tag, the target commit hash, and the changelog entry.
+
+Run the hickory/iroh gate before editing:
+
+1. Inspect the target tag's `veilid-tools/Cargo.toml` hickory dependency or scan the changelog for hickory changes.
+2. If Veilid still forces the resolver constraint that required `hickory-resolver = "=0.25.2"`, keep the hickory pins and iroh patches unchanged.
+3. If Veilid relaxed the constraint, drop the hickory pins and iroh patches only as a separate, well-tested change unless the user explicitly asks to combine it.
+4. For routine bumps, default to keeping the existing hickory pins and iroh patches.
+
+## Steps 1-3: Upgrade Each Repo
+
+For each repo in order:
+
+1. Inspect the current manifest:
+
+```bash
+rg 'veilid-core|veilid-tools|veilid-iroh-blobs|save-dweb-backend|hickory-resolver|patch.crates-io|tripledoublev|RangerMauve|OpenArchive' Cargo.toml
+```
+
+2. Edit `Cargo.toml`:
+
+- Update every `veilid-core` and `veilid-tools` git tag to the target Veilid tag.
+- Update downstream git tags only after the upstream repo's PR has merged and its release tag has been pushed.
+- Update all occurrences found by search, including target-specific dependency stanzas.
+- Bump the package version.
+- Leave hickory and iroh patch entries untouched unless Step 0 explicitly calls for a separate compatibility cleanup.
+
+3. Refresh the lockfile with package-aware commands from `references/dependency-map.md`.
+
+- Run `cargo update -p <pkg>` only for packages present in that repo.
+- If Cargo refuses a package target because of source ambiguity or graph absence, run a full lockfile refresh with `cargo update` or let `cargo build` resolve it.
+- Inspect `Cargo.lock` to confirm the new Veilid commit hash and any downstream git tag/hash landed.
+
+4. Build and test.
+
+- Use a normal fresh build in the current tree. Do not run `cargo clean` unless stale artifacts or dependency resolution make it necessary.
+- Discover smoke test names before invoking exact filters:
+
+```bash
+cargo nextest list
+cargo test -- --list
+```
+
+5. Open a PR and pause.
+
+- Verify default branch and permissions with `gh repo view --json defaultBranchRef` and git remote checks.
+- Create a branch named like `chore/veilid-0.5.x`.
+- Commit the repo-local upgrade.
+- Open a PR to the repo's default branch.
+- Stop and ask the human to review and merge.
+
+6. After merge, switch to the repo's default branch and fast-forward before tagging — the feature branch does not contain the squash/merge commit, so tagging without checking out the default branch tags the wrong commit. Do NOT assume `origin` is the release repo: the local `origin` may not point at it (e.g. veilid-iroh-blobs often has `origin` = RangerMauve and a separate `openarchive` remote = OpenArchive). Confirm with `git remote -v` and push the tag to the remote the PR actually merged into:
+
+```bash
+git remote -v                          # identify the release remote (the merged-into repo)
+RELEASE_REMOTE=origin                  # set to the verified release remote, e.g. openarchive
+git checkout <default-branch>          # usually 'main'; veilid-iroh-blobs uses 'default'
+git pull --ff-only "$RELEASE_REMOTE" <default-branch>
+git tag v<new-version>
+git push "$RELEASE_REMOTE" v<new-version>
+```
+
+7. Publish the GitHub Release from that tag. These repos keep a Release per tag, and a pushed git tag does NOT appear on the Releases page on its own. Only create a Release for a tag that is already on the merged default branch (never for an open PR). Match the repo's existing release-title convention:
+
+```bash
+gh release list --repo OpenArchive/<repo>        # confirm the title convention, e.g. "<repo> vX.Y.Z"
+gh release create v<new-version> --repo OpenArchive/<repo> --title "<repo> v<new-version>" --notes "..."
+```
+
+The next repo must not point at an upstream tag until that tag exists remotely.
+
+## Final save-rust Release
+
+Run the same loop for `save-rust`. Use the repo convention for the release commit, for example:
+
+```text
+chore: release v0.2.x
+```
+
+After its PR merges, tag and push the final `save-rust` release, then publish the GitHub Release (step 7). Create the Release only once every PR for this upgrade has merged, so it reflects the final merged state.
+
+## Verification
+
+- Each repo builds and tests before its PR.
+- `Cargo.lock` in each repo records the expected Veilid commit hash for the target tag.
+- Downstream repos point at the freshly pushed upstream release tags.
+- In `save-rust`, verify the new `save-dweb-backend` tag/hash and Veilid hash in `Cargo.lock`.
+- Search all three manifests for the PREVIOUS Veilid version (the one you upgraded FROM), escaped for regex — it should return nothing. Set `OLD_VEILID` to that concrete version; e.g. for a 0.5.5 → 0.5.6 bump use `0\.5\.5` (the unanchored match also covers the `v0.5.5` tag form):
+
+```bash
+OLD_VEILID='0\.5\.5'
+rg "${OLD_VEILID}" ../veilid-iroh-blobs/Cargo.toml ../save-dweb-backend/Cargo.toml Cargo.toml
+```

.claude/skills/veilid-upgrade/references/dependency-map.md

@@ -0,0 +1,228 @@
+# Veilid Upgrade Dependency Map
+
+Use this file after reading `SKILL.md`. Verify every fact against the live manifests before editing. Do not rely on line numbers.
+
+## Repo Layout
+
+The expected sibling checkout layout from `save-rust` is:
+
+```text
+../veilid-iroh-blobs
+../save-dweb-backend
+.
+```
+
+If a repo is missing, stop and ask the user whether to clone it, locate it, or skip that stage.
+
+## Current Dependency Chain
+
+```text
+veilid tag
+  -> veilid-iroh-blobs release tag
+  -> save-dweb-backend release tag
+  -> save-rust release tag
+```
+
+The downstream repo must not be updated until the upstream repo has a merged PR and a pushed release tag.
+
+## Shared Compatibility Patch
+
+The current compatibility workaround is:
+
+- `hickory-resolver = "=0.25.2"`
+- iroh patch entries under `[patch.crates-io]`
+
+Keep this workaround during routine Veilid bumps unless the target Veilid changelog or `veilid-tools/Cargo.toml` proves the resolver constraint has been relaxed. If it has been relaxed, remove the workaround as a separate PR unless the user explicitly asks to combine it.
+
+## Target Discovery
+
+Use one or both machine-readable checks:
+
+```bash
+git ls-remote --tags https://gitlab.com/veilid/veilid.git
+curl -fsS 'https://gitlab.com/api/v4/projects/veilid%2Fveilid/repository/tags?per_page=10'
+```
+
+Read the raw changelog:
+
+```bash
+curl -fsS https://gitlab.com/veilid/veilid/-/raw/main/CHANGELOG.md
+```
+
+If fetching from the network fails because of sandboxing, request approval for the same command rather than guessing the target.
+
+## veilid-iroh-blobs
+
+Path:
+
+```bash
+cd ../veilid-iroh-blobs
+```
+
+Important manifest entries to find with `rg`:
+
+```bash
+rg 'version =|veilid-core|hickory-resolver|patch.crates-io|iroh-net|tripledoublev' Cargo.toml
+```
+
+Expected dependency surfaces:
+
+- package version, currently in the `0.3.x` line
+- `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git`
+- `hickory-resolver = "=0.25.2"`
+- `[patch.crates-io] iroh-net` from `https://github.com/OpenArchive/iroh.git` after fork-origin migration, or the current manifest URL if migration has not landed yet
+
+Routine edit:
+
+- Update all `veilid-core` tag occurrences to the target Veilid tag.
+- Bump the package version, usually patch.
+- Keep hickory and iroh patch entries unless the Step 0 gate says otherwise.
+
+Lockfile refresh candidates:
+
+```bash
+cargo update -p veilid-core
+cargo build
+cargo test
+```
+
+If `cargo update -p veilid-core` is ambiguous or insufficient, use `cargo update`, then inspect `Cargo.lock`.
+
+Release handoff:
+
+- Open PR against the repo's default branch.
+- After merge, tag `v<new veilid-iroh-blobs version>` and push it.
+- `save-dweb-backend` cannot start until this tag exists remotely.
+
+## save-dweb-backend
+
+Path:
+
+```bash
+cd ../save-dweb-backend
+```
+
+Important manifest entries to find with `rg`:
+
+```bash
+rg 'version =|veilid-core|veilid-tools|veilid-iroh-blobs|hickory-resolver|patch.crates-io|tripledoublev|RangerMauve|OpenArchive' Cargo.toml
+```
+
+Expected dependency surfaces:
+
+- package version, currently in the `0.3.x` line
+- `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git`
+- `veilid-tools` git tag from `https://gitlab.com/veilid/veilid.git`
+- `veilid-iroh-blobs` git tag from `https://github.com/OpenArchive/veilid-iroh-blobs` after fork-origin migration, or the current manifest URL if migration has not landed yet
+- `hickory-resolver = "=0.25.2"`
+- seven `[patch.crates-io]` iroh workspace crates from `https://github.com/OpenArchive/iroh.git` after fork-origin migration, or the current manifest URL if migration has not landed yet
+
+Routine edit:
+
+- Update all `veilid-core` and `veilid-tools` tag occurrences to the target Veilid tag.
+- Update `veilid-iroh-blobs` to the tag pushed from the previous repo.
+- Bump the package version, usually patch.
+- Keep hickory and iroh patch entries unless the Step 0 gate says otherwise.
+
+Lockfile refresh candidates:
+
+```bash
+cargo update -p veilid-core -p veilid-tools -p veilid-iroh-blobs
+cargo build
+cargo nextest run
+```
+
+If any `-p` target fails because the package is absent or ambiguous, run narrower `cargo update -p` commands or a full `cargo update`, then inspect `Cargo.lock`.
+
+Test workflow — save-dweb-backend's CI runs the full suite, so run it all. `.config/nextest.toml` already serializes and retries the flaky Veilid P2P/DHT tests:
+
+```bash
+cargo nextest run
+```
+
+To narrow to specific tests, discover names first and pass them as a filter EXPRESSION with `-E`. A bare quoted string WITHOUT `-E` is a substring match and silently runs 0 tests:
+
+```bash
+cargo nextest list
+cargo nextest run -E 'test(parse_url_rejects_malformed_url)'
+```
+
+Release handoff:
+
+- Open PR against the repo's default branch.
+- After merge, tag `v<new save-dweb-backend version>` and push it.
+- `save-rust` cannot start until this tag exists remotely.
+
+## save-rust
+
+Path:
+
+```bash
+cd <save-rust checkout>
+```
+
+Important manifest entries to find with `rg`:
+
+```bash
+rg 'version =|save-dweb-backend|veilid-core|hickory-resolver|patch.crates-io|tripledoublev' Cargo.toml
+```
+
+Expected dependency surfaces:
+
+- package name `save`
+- package version, currently in the `0.2.x` line
+- `save-dweb-backend` git tag from `https://github.com/OpenArchive/save-dweb-backend`
+- `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git`
+- an additional Android-target `veilid-core` dependency
+- `hickory-resolver = "=0.25.2"`
+- seven `[patch.crates-io]` iroh workspace crates from `https://github.com/OpenArchive/iroh.git` after fork-origin migration, or the current manifest URL if migration has not landed yet
+
+Routine edit:
+
+- Update all `veilid-core` tag occurrences to the target Veilid tag.
+- Update `save-dweb-backend` to the tag pushed from the previous repo.
+- Bump the package version, usually patch.
+- Keep hickory and iroh patch entries unless the Step 0 gate says otherwise.
+
+Lockfile refresh candidates:
+
+```bash
+cargo update -p veilid-core -p save-dweb-backend
+cargo build
+cargo nextest run
+```
+
+If any `-p` target fails because the package is absent or ambiguous, run narrower `cargo update -p` commands or a full `cargo update`, then inspect `Cargo.lock`.
+
+Smoke-test workflow — match CI's smoke set. Pass the filter as an EXPRESSION with `-E`; without `-E` the quoted string is a substring match and silently runs 0 tests:
+
+```bash
+cargo nextest list
+cargo nextest run -E 'test(basic_test) | test(test_health_endpoint) | test(test_upload_list_delete)'
+```
+
+Only use exact test filters after confirming the names still exist.
+
+Release:
+
+- Use a release commit message like `chore: release v0.2.x`.
+- Open PR against the repo's default branch.
+- After merge, tag `v<new save-rust version>` and push it.
+
+## Fork-Origin Migration
+
+Do this only as a standalone change unless the user explicitly asks otherwise.
+
+OpenArchive fork URLs:
+
+- `https://github.com/OpenArchive/veilid-iroh-blobs`
+- `https://github.com/OpenArchive/iroh.git`
+
+Migration checklist:
+
+1. Update the `veilid-iroh-blobs` git URL in `save-dweb-backend` (and any other direct consumer) to the OpenArchive fork.
+2. Update every `[patch.crates-io]` iroh entry in all three repos to `OpenArchive/iroh`.
+3. Refresh lockfiles so the source hashes repoint to the OpenArchive forks. Do NOT change the **Veilid version tags** — `veilid-core`/`veilid-tools` stay on their current `vX.Y.Z`.
+4. Build and test all affected repos.
+5. Keep each repo's diff focused on fork origins + lockfile source hashes — no Veilid version change.
+6. Separate from the Veilid tags above, you will likely need to cut **new wrapper-crate release tags** so downstream repos can consume the merged fork-origin commits. Never move an existing pushed tag — instead bump the wrapper package `version` and tag the new version: e.g. release `veilid-iroh-blobs` (bump `version`, tag `v0.3.x`) after its migration merges, then `save-dweb-backend` (bump `version`, tag `v0.3.y`), repointing each downstream git tag the same way the Veilid cascade does. This is a wrapper-crate release bump, distinct from a Veilid version change.

AGENTS.md

@@ -0,0 +1,17 @@
+# Agent Guidance
+
+## Veilid Cross-Repo Upgrades
+
+For Veilid upgrades, read `.claude/skills/veilid-upgrade/SKILL.md` and `.claude/skills/veilid-upgrade/references/dependency-map.md`, then follow that runbook.
+
+The `.claude/skills/...` directory is a Claude Code skill location, not a native Codex skill trigger. For Codex, this `AGENTS.md` file is the discoverability pointer.
+
+Assume the sibling repo layout:
+
+```text
+../veilid-iroh-blobs
+../save-dweb-backend
+.
+```
+
+Upgrade in dependency order: `veilid-iroh-blobs`, then `save-dweb-backend`, then `save-rust`. Locate dependency pins with `rg` or package keys, not line numbers. Keep fork-origin migration separate from Veilid version bumps unless the user explicitly asks to combine them.