@caddis/cli 0.4.19 → 0.4.21

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.111",
+  "version": "1.3.112",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/skills/_registry.md

@@ -39,6 +39,7 @@
 | Ci Cd Pipeline | `ci-cd-pipeline/` | CI/CD pipeline design and implementation for GitHub Actions, Azure DevOps, and general pipeline architecture. Use when creating build pipelines, deployment workflows, quality gates, environment promotion strategies, or automating release processes. |
 | Gh Cli | `gh-cli/` | GitHub CLI operations — issues, PRs, releases, and repo management |
 | Git Commit | `git-commit/` | Create well-structured conventional commit messages following Conventional Commits standard. Use when committing changes, preparing PRs, or generating changelogs. |
+| Port To Github | `port-to-github/` | Move (port) an app or repository to GitHub from ANY source - a Gitea/GitLab/any git server URL, a local folder, a network (UNC) share, or a folder on a remote Windows box reached over WinRM - with or without existing git history. Keeps every branch and tag, verifies by SHA, translates Gitea/Forgejo Actions CI, switches deploy checkouts to GitHub with automatic rollback, and retires the old host safely. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from Gitea", "put this folder on GitHub", "this app only exists on the server", "import the repo from the prod box", or "cut the deploy over to GitHub". |
 | Safe Cleanup | `safe-cleanup/` | Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment. |
 | Using Git Worktrees | `using-git-worktrees/` | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification |
 | Windows Deployment | `windows-deployment/` | Deploy FastAPI + React/Vite apps to Windows Server with NSSM services, reverse proxy (IIS or nginx), and git-pull workflow. Use when deploying any web app to a Windows prod server, setting up NSSM services, configuring IIS or nginx reverse proxy, making code environment-aware for dev/prod, or troubleshooting prod deployment issues. |
@@ -49,9 +50,10 @@
 |-------|------|-------------|
 | Code Documentation | `code-documentation/` | Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides. |
 | Confluence Hla | `confluence-hla/` | Author enterprise High-Level Architecture (HLA) documents in Simplified Technical English and generate Confluence Storage Format XHTML with self-contained PlantUML diagrams, wrapped tables, and zero AI fingerprints. Use when creating high-level architecture designs, architecture documentation for Confluence, or converting markdown architecture to Confluence storage format. |
+| Data Lineage | `data-lineage/` | Generate End-to-End Data Lineage and Telemetry Specification Markdown and Confluence XHTML for fleet observability. |
 | Explainer Doc | `explainer-doc/` | Write a document that hands off work to a team who did NOT do the investigation — an external vendor, another team, a contractor — and who must be able to act on it alone. Use when the user says "write a spec for the X team", "document this for someone outside the team", "explainer doc", "implementation spec for a vendor", "hand this off to Y", or is about to write a design doc whose primary reader did not live through the debugging/design process. NOT for internal specs where the reader already has full context (use technical-writing or writing-plans instead) — this is specifically for the "stranger must follow it alone" case. |
-| Hld | `hld/` | Generate High-Level Design (HLD) Markdown documentation and Confluence XHTML with Draw.io diagrams. |
-| Lld | `lld/` | Generate Lower-Level Design (LLD) Markdown documentation and Confluence XHTML with Draw.io diagrams. |
+| Hld | `hld/` | Generate High-Level Design (HLD) Markdown documentation and Confluence XHTML with native PlantUML diagrams. |
+| Lld | `lld/` | Generate Lower-Level Design (LLD) Markdown documentation and Confluence XHTML with native PlantUML diagrams. |
 | Tech Explainer | `tech-explainer/` | >- |
 | Technical Writing | `technical-writing/` | Technical documentation best practices for READMEs, API docs, architecture docs, runbooks, and developer guides. Use when writing or reviewing documentation, creating onboarding guides, or establishing documentation standards. |
 | Writing Plans | `writing-plans/` | Use when you have a spec or requirements for a multi-step task, before touching code |

package/bundles/antigravity-plugin/skills/data-lineage/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: data-lineage
+description: Generate End-to-End Data Lineage and Telemetry Specification Markdown and Confluence XHTML for fleet observability.
+---
+
+# /data-lineage Command
+
+Run the End-to-End Data Lineage generation procedure:
+
+1. **Target Architecture & Telemetry Discovery:**
+   - Scan target application routes, pages, and controllers.
+   - Trace API handlers down to physical tables, views, and columns.
+   - Identify database server stored procedures, batch scripts, and scheduled SQL Agent jobs that populate each dataset.
+   - Cross-reference estate configuration catalogs to identify hostnames, IPs, ports, and synthetic health probe endpoints.
+
+2. **Author Canonical Markdown Document:**
+   - Create document at `docs/<app>/<app>-data-lineage.md`.
+   - Adhere strictly to the standard 5-section lineage structure:
+     1. Physical Estate & Host Infrastructure (servers, IPs, ports, database instances, access methods).
+     2. End-to-End Dependency & Impact Flowchart (vibrant Mermaid flowchart from feeds down to UI surfaces).
+     3. Comprehensive 7-Column Lineage Matrix (`App`, `UI Page`, `API Route`, `Dataset`, `Producer`, `Database`, `Physical Host`).
+     4. Stored Procedures & Producer Execution Catalog (schedules, triggers, parameters, source and target tables).
+     5. Telemetry Ingestion Contract (machine-readable JSON target graph).
+   - Use ASD-STE100 Simplified Technical English: active voice, short sentences, zero em-dashes.
+
+3. **Convert to Confluence Storage Format XHTML:**
+   - Run the PlantUML-enabled converter:
+     ```powershell
+     python scripts/convert_doc_to_confluence.py docs/<app>/<app>-data-lineage.md --output docs/<app>/<app>-data-lineage.html --diagram-type plantuml
+     ```
+   - Verify that all diagrams convert to native `<ac:structured-macro ac:name="plantuml">` blocks with scale 1.2, natural splines, auto-wrapped edge labels, crimson red borders on impacted components, and embedded Creole legends.
+   - Verify that output validates as 100% well-formed XML.

package/bundles/antigravity-plugin/skills/hld/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hld
-description: Generate High-Level Design (HLD) Markdown documentation and Confluence XHTML with Draw.io diagrams.
+description: Generate High-Level Design (HLD) Markdown documentation and Confluence XHTML with native PlantUML diagrams.
 ---
 
 # /hld Command
@@ -12,16 +12,28 @@ Run the High-Level Design (HLD) generation procedure:
    - Enforce HLD boundaries: exclude internal API routes, low-level stored procedures, and detailed ETL scripts.
    - Use high-level reporting summary tables and domain entities only.
 
-2. **Author Canonical Markdown Document:**
+2. **Component & Interface Classification Interview (Grill-Me):**
+   - **MANDATORY GATE:** Present discovered systems (`SYS_xx`) and interfaces (`INT_xx`) to the user.
+   - Ask the user to confirm/clarify:
+     - Which systems/components are Existing fleet infrastructure (`Impacted = No`, Blue `#1D4ED8`) vs New / Impacted (`Impacted = Yes`, Red `#DC2626`)?
+     - Which interfaces are Existing Connectivity (Green `#16A34A`) vs New Connectivity (Red `#DC2626`)?
+   - Formulate recommendations from codebase discovery and seek user sign-off in a single interactive turn.
+
+3. **Author Canonical Markdown Document:**
    - Create document at `docs/<app>/<app>-hld.md`.
-   - Adhere strictly to the standard 7-section HLD structure.
+   - Adhere strictly to the standard HLD structure.
+   - **Do not synthesize or fabricate "Target Architecture", "Target State Roadmap", or "Security Topology" sections/diagrams** when there are no notes mentioning future architecture and the user does not request them. Only include them when explicitly requested by the user or specified in existing project notes as future work.
+   - Place the core architecture diagram in Section 4 titled `### 4.1 Solution Design and Architecture` under `## 4. Solution Architecture Landscape`. Do not use `System Topology Architecture Diagram` or place it in Section 2.
+   - Represent domain data models in Section 5 (`### 5.2 Domain Entity Model`) using Mermaid `classDiagram` or `erDiagram` syntax, converted natively to PlantUML.
    - Ensure Mermaid diagrams depict automated schedulers as system participants, not human actors.
+   - Use colorful, professional Mermaid diagrams with explicit `classDef` styling palettes (no raw yellow boxes).
    - Use ASD-STE100 Simplified Technical English: active voice, short sentences, zero em-dashes.
 
-3. **Convert to Confluence Storage Format XHTML:**
-   - Run the Draw.io-enabled converter:
-     ```bash
-     python scripts/convert_doc_to_confluence.py docs/<app>/<app>-hld.md --output docs/<app>/<app>-hld.html
+4. **Convert to Confluence Storage Format XHTML:**
+   - Run the PlantUML-enabled converter:
+     ```powershell
+     python scripts/convert_doc_to_confluence.py docs/<app>/<app>-hld.md --output docs/<app>/<app>-hld.html --diagram-type plantuml
      ```
-   - Verify that all diagrams are converted to native `<ac:structured-macro ac:name="drawio">` blocks.
+   - Verify that all diagrams are converted to native `<ac:structured-macro ac:name="plantuml">` blocks with scale 1.2, natural splines, auto-wrapped edge labels, crimson red borders on impacted components, and embedded Creole legends.
+   - Ensure multi-stage operational flows use horizontal side-by-side stages (`flowchart LR`) and architecture topologies follow clean 3-tier hierarchies (`flowchart TD`).
    - Verify that output validates as well-formed XML.

package/bundles/antigravity-plugin/skills/lld/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lld
-description: Generate Lower-Level Design (LLD) Markdown documentation and Confluence XHTML with Draw.io diagrams.
+description: Generate Lower-Level Design (LLD) Markdown documentation and Confluence XHTML with native PlantUML diagrams.
 ---
 
 # /lld Command
@@ -11,20 +11,35 @@ Run the Lower-Level Design (LLD) generation procedure:
    - Scan physical hosts, service managers (NSSM, systemd), environment configurations, and ports.
    - Extract internal API routes, controllers, middleware, and dependency injection patterns.
    - Inspect database schemas, tables, views, primary keys, and index configurations.
-   - Catalog stored procedures (`usp_*`), parameter lists, business logic flows, and return codes.
-   - Map batch ingestion scripts, command-line arguments, and background refresher polling loops.
+   - Catalog stored procedures (`usp_*`), parameter lists, analytical logic flows, and discrepancy output structures.
+   - Map ETL scripts, daily/monthly cron schedules, record volumes, idempotency logic, and shared audit tables (e.g. `ETL_AUDIT_LOG`).
+   - Map background refresher loops, polling intervals, watermark sync, and caching tiers.
+   - Map UI screens to stable query IDs (`QRY-*`), API endpoints, repository methods, and source tables.
 
-2. **Author Canonical Markdown Document:**
+2. **Component & Interface Classification Interview (Grill-Me):**
+   - **MANDATORY GATE:** Present discovered internal components (`SYS_Lxx`) and internal interfaces (`INT_Lxx`) to the user.
+   - Ask the user to confirm/clarify:
+     - Which internal components are New / Impacted (`Impacted = Yes`, Red `#DC2626`) vs Existing fleet databases/services (`Impacted = No`, Blue `#1D4ED8`)?
+     - Which interfaces are Existing Connectivity (Green `#16A34A`) vs New Connectivity (Red `#DC2626`)?
+   - Seek user sign-off in a single interactive turn before drafting diagrams.
+
+3. **Author Canonical Markdown Document:**
    - Create document at `docs/<app>/<app>-lld.md`.
-   - Adhere strictly to the standard 7-section LLD structure.
-   - Detail every stored procedure, table, ETL job, and endpoint contract.
-   - Include detailed Mermaid sequence, flowchart, and component interaction diagrams.
+   - Adhere strictly to the standard LLD structure including the 5 mandatory technical sections:
+     1. Operational Process Flow (multi-stage batch, validation, refresh, and serving pipeline)
+     2. End-to-End Operational Sequence Diagram (technical interaction sequence)
+     3. Detailed Solution Architecture Landscape (`SYS_Lxx` components, `INT_Lxx` interfaces, Applications and Interfaces tables)
+     4. End-to-End Database and Data Processing Pipeline (staging, validation, mart rollup, API extraction)
+     5. End-to-End Database Lineage Specification (complete domain -> source -> staging -> SP -> mart -> API -> UI matrix)
+   - Dissect every ETL pipeline with schedules, row volumes, and idempotency.
+   - Detail stored procedures catalog with parameters, join logic, and thresholds.
+   - Use colorful, professional Mermaid diagrams with explicit `classDef` styling palettes (no raw yellow boxes).
    - Use ASD-STE100 Simplified Technical English: active voice, short sentences, zero em-dashes.
 
-3. **Convert to Confluence Storage Format XHTML:**
-   - Run the Draw.io-enabled converter:
-     ```bash
-     python scripts/convert_doc_to_confluence.py docs/<app>/<app>-lld.md --output docs/<app>/<app>-lld.html
+4. **Convert to Confluence Storage Format XHTML:**
+   - Run the PlantUML-enabled converter:
+     ```powershell
+     python scripts/convert_doc_to_confluence.py docs/<app>/<app>-lld.md --output docs/<app>/<app>-lld.html --diagram-type plantuml
      ```
-   - Verify that all diagrams are converted to native `<ac:structured-macro ac:name="drawio">` blocks.
+   - Verify that all diagrams are converted to native `<ac:structured-macro ac:name="plantuml">` blocks with scale 1.2, natural splines, auto-wrapped edge labels, crimson red borders on impacted components, and embedded Creole legends.
    - Verify that output validates as well-formed XML.

package/bundles/antigravity-plugin/skills/port-to-github/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: port-to-github
+description: Move (port) an app or repository to GitHub from ANY source - a Gitea/GitLab/any git server URL, a local folder, a network (UNC) share, or a folder on a remote Windows box reached over WinRM - with or without existing git history. Keeps every branch and tag, verifies by SHA, translates Gitea/Forgejo Actions CI, switches deploy checkouts to GitHub with automatic rollback, and retires the old host safely. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from Gitea", "put this folder on GitHub", "this app only exists on the server", "import the repo from the prod box", or "cut the deploy over to GitHub".
+---
+
+# port-to-github
+
+Move one app to GitHub without losing history, leaking a secret, or breaking its deploy.
+
+The work is in **six phases**. Each ends in a check that can FAIL. Do not start a phase until
+the one before it passed. Scripts are in `scripts/` next to this file. They are PowerShell 7
+(`pwsh`); the parts that run on a remote box are Windows PowerShell 5.1 compatible.
+
+| Phase | Script | Changes anything outside this machine? |
+|---|---|---|
+| 1. Stage the source | `Get-PortSource.ps1` | No. The source is only read. |
+| 2. Readiness | `Test-PortReadiness.ps1` | No. |
+| 3. Publish | `Publish-PortToGitHub.ps1` | **Yes: creates a GitHub repo and pushes.** |
+| 4. CI | `Convert-PortWorkflow.ps1`, `Test-PortWorkflowParses.ps1` | Yes: a feature branch and a PR. |
+| 5. Cutover | `Switch-CheckoutOrigin.ps1` | **Yes: changes where a deploy host pulls from.** |
+| 6. Retire the old host | manual, see `references/old-host.md` | **Yes, and can be destructive.** |
+
+**Stop and ask the user before phases 3, 5 and 6.** Each one is outward-facing. Say exactly
+what will be created or changed, on which host, and how to undo it.
+
+Not every port needs every phase. A folder that never had CI or a deploy host ends after
+phase 3. Say which phases apply and why, before you start.
+
+## Before you start
+
+1. **Read the project config**, if one exists: `.caddis/port-to-github.json` in the repo you are
+   working from (or `$env:PORT_TO_GITHUB_CONFIG`). It sets the GitHub `owner`, `visibility`,
+   staging folder, the name for the old remote, dependency hosts and their secrets, and
+   `projectNotes` - pointers to the project's own rules. **Read every file `projectNotes` names
+   before phase 4.** Project rules beat this skill. The shape is in `references/config.example.json`.
+2. `gh auth status` must show an account that can create repos in the owner. `git` must be able
+   to push to github.com (run `gh auth setup-git` once if not).
+3. **Find the authoritative copy.** If a folder is a clone of a server, port from the SERVER
+   URL, not the folder: the folder may lack branches the server has. Port from a folder only
+   when it is the only copy, or when it holds commits the server lacks. Phase 1 reports both
+   cases.
+
+## Phase 1 - stage the source
+
+```powershell
+$s = '<path-to-this-skill>/scripts'
+& $s/Get-PortSource.ps1 -Source <source> [-Name <repo-name>] [-IncludeUncommitted]
+```
+
+| Source | Example `-Source` |
+|---|---|
+| any git server | `https://gitea.example/org/app.git`, `git@host:org/app.git` |
+| local folder | `D:\work\app` |
+| network share | `\\fileserver\projects\app` |
+| remote box (WinRM) | `winrm://appserver01/D:/apps/app` (or `-ComputerName appserver01 -Source D:\apps\app`) |
+
+What it does, for every kind: builds `<staging>/<Name>/mirror.git` holding ONLY branches and
+tags, removes the remote so nothing can be pushed back to the source, and writes
+`manifest.json`. A folder without history becomes one import commit; `node_modules`, virtual
+envs and caches are skipped, and a `.gitignore` is written if there was none.
+
+Read the output. These need a decision, not a shrug:
+
+- **Uncommitted changes** in a source checkout are left out unless you pass
+  `-IncludeUncommitted`, which puts them on a separate branch `port/uncommitted-snapshot-*`.
+  The real branches stay exactly as committed. Ask the user which they want.
+- **Remote-only branches**: branches the checkout only knows as `origin/x`. If the checkout is
+  the only copy, re-run with `-PromoteRemoteBranches origin`. If a server has them, port from it.
+- **Likely secrets** in a plain folder or a snapshot stop the script (exit 2). Nothing has left
+  the machine. Show the user the list. Re-run with `-OnSecret Exclude` only after they agree
+  those files must not be published.
+- **Dropped refs** (`refs/pull/*`, `refs/remotes/*`, notes) are expected. GitHub refuses
+  `refs/pull/*`, and pull-request discussion does not move with git anyway. If the old host's
+  PR and issue history matters, export it before phase 6.
+
+## Phase 2 - readiness
+
+```powershell
+& $s/Test-PortReadiness.ps1 -Name <repo-name>
+```
+
+**Blockers (exit 1) must be fixed before phase 3:** a file over 100 MB anywhere in history,
+Git LFS content, a likely live credential in the current tree, an empty `${{ }}` in a file
+under `.github/workflows`. A credential found in the tree must be **rotated**, not only
+deleted: history keeps it. (An empty `${{ }}` in a `.gitea/` workflow is only a warning here:
+GitHub does not read that folder, so it matters in phase 4.)
+
+**Branches that already contain `.github/workflows` run them the moment they are pushed** -
+deploy jobs included. Readiness lists those branches; publish refuses them unless you pass
+`-AllowWorkflowRuns`, which you do only after reading every such workflow with the user.
+
+**Warnings are decisions.** Go through each with the user: secret-type files in past history
+(the new repo will expose them), CI credentials, dependency hosts, runner labels, files that
+still name the old host. The report is in `readiness.json`.
+
+## Phase 3 - publish (ask first)
+
+Tell the user: the repo name, owner, visibility, branch and tag counts. Then:
+
+```powershell
+& $s/Publish-PortToGitHub.ps1 -Name <repo-name> [-Owner <org>] [-Visibility private]
+```
+
+It first checks the stage still holds exactly the refs phase 1 recorded (anything else would be
+pushed and then "verified" against itself), creates the repo EMPTY, pushes `refs/heads/*` and
+`refs/tags/*` with an explicit refspec, sets the default branch, and compares every ref by SHA
+(exit 1 on any difference). Do not run other git commands inside the stage; if you did,
+rebuild it with `Get-PortSource.ps1 -Force`.
+
+- **Never** `git push --mirror`: it tries to push hidden refs, fails AFTER pushing the rest (so
+  a populated repo reports failure), and deletes anything on GitHub the stage lacks.
+- **An existing repo.** If one exists with history, the script refuses. Find out whether it
+  shares history with the source: for a few of its commit SHAs, `git -C mirror.git cat-file -e
+  <sha>^{commit}`. If it shares nothing (for example a snapshot someone uploaded with a fresh
+  "Initial commit"), pushing on top welds a fake ancestry in forever: save anything of value
+  from it, delete it, and re-run. Use `-AllowExisting` only when it is a genuine older copy; the
+  script then requires every GitHub branch to be an ancestor of the staged one.
+- Verify with the SHA comparison, never by counting refs or by "the push said OK".
+
+Stop here if the app has no CI and no deploy host. Otherwise continue.
+
+## Phase 4 - CI
+
+Work in a normal clone of the NEW repo, on a feature branch.
+
+```powershell
+git clone https://github.com/<owner>/<repo>.git; cd <repo>; git switch -c port/github-actions
+& $s/Convert-PortWorkflow.ps1 -AddPermissions [-SourceRef <sha>]
+```
+
+It copies `.gitea/workflows` (or `.forgejo/workflows`) to `.github/workflows`, rewrites the
+`gitea.` context to `github.`, and prints every credential line. **Leave the scripts the
+workflows call where they are** - GitHub only needs the workflow file under `.github/`.
+
+Then do by hand, one line at a time - this is the whole job, and a blanket swap breaks it:
+
+1. **Classify every credential line.** It faces ORIGIN (checkout, fetch, reset, pushing a tag
+   back to this repo) or it names a DEPENDENCY host (a package registry, a library pinned from
+   another repo or server). There is no third category.
+   - ORIGIN -> `${{ github.token }}`, username `x-access-token`. This includes an
+     `actions/checkout` that pushes tags - it is easy to miss.
+   - DEPENDENCY -> a secret valid for THAT host. `github.token` reads only the repo whose
+     workflow is running, so a library in ANOTHER GitHub repo needs its own read token.
+   One job can hold two credential pairs that serve different hosts. Change only the pair
+   that faces origin.
+2. **One Authorization header per host.** `http.<url>.extraheader` values ACCUMULATE; two for the
+   same host is an HTTP 400. `actions/checkout` persists its own header, so a step that adds
+   another for github.com must unset the checkout's for that command and restore it after.
+3. **npm and GitHub dependencies:** npm fetches a GitHub dependency over SSH even when
+   `package.json` says `https`. Set `url.https://github.com/.insteadOf=ssh://git@github.com/`
+   and `GIT_TERMINAL_PROMPT=0` so a missing credential fails in seconds instead of hanging.
+4. **Runner labels** must exist on GitHub (`runs-on:`). Self-hosted runners must be registered
+   to the org or repo, not only to the old host.
+5. **Never write `${{ }}` in any text in a workflow**, including comments inside `run:` blocks.
+6. **If a workflow was frozen** on the old host (triggers reduced to `workflow_dispatch`), pass
+   `-SourceRef` with the last commit before the freeze. A workflow built from a frozen copy
+   fires on nothing, which looks like "still queued", not like a fault.
+
+Details and the credential patterns: `references/ci-and-credentials.md`.
+
+**Validate before anything reaches `main`.** Commit the workflow files BY NAME, push the branch,
+then:
+
+```powershell
+& $s/Test-PortWorkflowParses.ps1 -Owner <owner> -Repo <repo> -Branch port/github-actions
+```
+
+An unparseable workflow produces a failed run with zero jobs even on a branch its triggers
+ignore; a valid one produces no run (or a normal run). A broken workflow on `main` leaves the
+app with no deploy path, so this check is not optional. Then open a PR and let the real jobs
+run; merging follows the repo's normal rules.
+
+## Phase 5 - cutover (ask first)
+
+Only for apps with a deploy host whose checkout pulls from the old origin. Order matters:
+
+1. `Switch-CheckoutOrigin.ps1 -Mode Inspect` on each host. Record what it prints.
+2. **Tell the user** the host, path, old and new URL, and the rollback command.
+3. Switch:
+   ```powershell
+   & $s/Switch-CheckoutOrigin.ps1 -Path D:\apps\app [-ComputerName appserver01] -Mode Switch `
+       -NewUrl https://github.com/<owner>/<repo>.git -VerifyWithGhToken
+   ```
+   It records the old URL first, keeps it as a second remote, fetches, and requires the
+   checkout's HEAD to be on a GitHub branch. On failure it restores the old origin itself.
+   `-VerifyWithGhToken` lends your gh token to that one fetch, in memory only, because a deploy
+   host normally has no GitHub credential of its own (CI supplies one per run).
+4. **Stop the old host from deploying** (disable its deploy job) only AFTER the first GitHub
+   deploy is green. Two schedulers on one checkout have no lock between them.
+5. **Verify the deploy by an artefact changing** - a built bundle's hash or file time - never by
+   an HTTP 200 or a version endpoint alone. Both pass when a new backend serves an old frontend.
+
+Rollback, at any point before phase 6:
+
+```powershell
+& $s/Switch-CheckoutOrigin.ps1 -Path D:\apps\app [-ComputerName appserver01] -Mode Rollback
+```
+
+Also repoint developer checkouts the same way (`-Mode Switch` without `-VerifyWithGhToken`), so
+`git push` goes to GitHub. Keep the old remote; it is the local rollback.
+
+## Phase 6 - retire the old host (ask first)
+
+Read `references/old-host.md`. The short version:
+
+- Prove nothing is lost first:
+  `& $s/Compare-PortRefs.ps1 -Left <old-url> -Right <github-url> -Mode LeftInRight` must exit 0.
+  Push any ref that exists only on the old host before you continue.
+- Prefer a **read-only pull mirror** of GitHub on the old host (Actions off) over deleting it:
+  anything still pinned to the old URL keeps working. Never a push mirror from CI.
+- Anything that still pins a dependency from the old host keeps the old host alive. Find those
+  pins before retiring it.
+
+## Report
+
+End with a short table per app: source kind, branches and tags ported (SHA-verified yes/no),
+warnings accepted and by whom, CI state, cutover state and rollback command, what is left.
+Say which phases were skipped and why.
+
+## Rules that apply to every phase
+
+- Stage files BY NAME. The only `git add -A` is inside the scripts, on fresh throwaway trees.
+- A check that cannot fail is not a check. Every script here exits non-zero on the failure it
+  exists for; do not pipe it to `Out-Null` or read only its last line.
+- Audit the default branch on the SERVER (`origin/main`), never a working tree that may sit on
+  an old feature branch.
+- Code that runs on a remote box runs under Windows PowerShell 5.1. There, with
+  `$ErrorActionPreference='Stop'`, a native command's stderr is a terminating error even with
+  `2>$null`. Use `'Continue'` and judge native commands by `$LASTEXITCODE`.
+- One variable at a time. When a whole batch fails the same way, change one thing and retry
+  one item before re-reading the request.

package/bundles/antigravity-plugin/skills/port-to-github/references/ci-and-credentials.md

@@ -0,0 +1,66 @@
+# CI and credentials after a port
+
+Every item here broke a real deploy at least once.
+
+## The two kinds of credential
+
+| Faces | Examples | On GitHub |
+|---|---|---|
+| ORIGIN - this repo | `actions/checkout`, a deploy script's `git fetch`/`reset`, pushing a version tag back | `${{ github.token }}`, username `x-access-token`. Needs `permissions: contents: write` to push. Nothing to store or rotate. |
+| DEPENDENCY - another host or repo | a library pinned `git+https://host/org/lib.git@v1`, a private npm/PyPI registry, a Git server that stays behind | A secret that can read THAT host. `github.token` cannot read a different repo, even in the same org. |
+
+Choose the credential **per host**, from the host named in the pin, never from where the app is
+hosted. When a pin moves from the old server to GitHub, its credential must move with it in the
+same commit; when an app moves but its pins do not, the old credential must stay.
+
+A deploy script that builds its auth header from `git remote get-url origin` needs NO change
+for the origin half: repointing origin (phase 5) is the whole cutover. It DOES need a change if
+it also uses that origin-derived credential for dependency clones - the moment origin is
+GitHub and the dependency is not, that pairing is wrong.
+
+## Injecting a credential for a child process (pip, npm)
+
+`GIT_CONFIG_*` environment entries (git 2.31+) are inherited by every git a tool spawns:
+
+```yaml
+env:
+  GIT_CONFIG_COUNT: '2'
+  GIT_CONFIG_KEY_0: http.https://github.com/.extraheader
+  GIT_CONFIG_VALUE_0: AUTHORIZATION: basic <base64 of x-access-token:TOKEN>
+  GIT_CONFIG_KEY_1: http.https://old-host.example/.extraheader
+  GIT_CONFIG_VALUE_1: AUTHORIZATION: basic <base64 of user:OLD_HOST_TOKEN>
+```
+
+Add a new entry and increment the count. Never replace entry 0 when another host still needs
+it. Build the base64 in a script step from `env:`; never put a token in a URL - it lands in
+lockfiles and logs.
+
+## Traps
+
+- **Header accumulation.** `http.<url>.extraheader` never overrides; git sends every matching
+  one. `actions/checkout` persists one in `.git/config`. A second for the same host -> HTTP 400
+  `Duplicate header: "Authorization"`. Unset the checkout's entry for the one command that
+  needs a different credential, then restore it; otherwise every later step loses its auth.
+- **`git config --local` outside a repo fails.** A runner's temp working directory is not a
+  repository. Check `git rev-parse --is-inside-work-tree` first.
+- **npm uses SSH for GitHub deps** despite `https` in `package.json` and the lockfile. Add
+  `url.https://github.com/.insteadOf ssh://git@github.com/`. Also make sure the lockfile's
+  `resolved` URLs say `git+https`, not `git+ssh`.
+- **A cache hit is not proof of credentials.** A warm npm or pip cache skips the authenticated
+  fetch entirely. Prove a new credential with a fresh install (cleared cache, empty `HOME`, no
+  credential helper).
+- **Windows PowerShell 5.1 runners.** With `$ErrorActionPreference='Stop'`, anything a native
+  exe writes to stderr becomes a terminating error, and `2>$null` does not prevent it. Use
+  `'Continue'` in the step, `2>&1 | Out-Null` to silence, and judge by `$LASTEXITCODE`.
+- **A step whose last native command is EXPECTED to fail** (a negative test) must end with
+  `exit 0`, or the step is red after printing its pass.
+- **Required checks.** A job skipped by a path filter at the TRIGGER never reports, so making it
+  a required check blocks every PR that does not touch those paths. A job skipped by `if:` counts
+  as passed. Renaming a job renames its check context and silently breaks a branch rule.
+- **`concurrency: cancel-in-progress`** cancels a PR's running jobs when you push again. A
+  `cancelled` job or a PR with no runs is often this, not a fault. Re-check against the new
+  head SHA.
+- **Deploy scripts may run from the deploy checkout**, not from the commit being deployed. If the
+  workflow syncs that checkout to the target commit before calling the script, a script change
+  takes effect on the first deploy; if it does not, it takes effect on the NEXT deploy. Check
+  which before predicting.

package/bundles/antigravity-plugin/skills/port-to-github/references/config.example.json

@@ -0,0 +1,18 @@
+{
+  "_comment": "Copy to .caddis/port-to-github.json in the repo you run the port from. Every field is optional.",
+  "owner": "example-org",
+  "visibility": "private",
+  "stagingRoot": "%TEMP%\\port-to-github",
+  "oldRemoteName": "gitea",
+  "dependencyHosts": [
+    { "host": "github.com", "username": "x-access-token", "secret": "ORG_READ_TOKEN", "note": "libraries in other repos of the org" },
+    { "host": "git.example.internal", "username": "ci-bot", "secret": "OLD_HOST_READ_TOKEN", "note": "stays until nothing pins from it" }
+  ],
+  "deployHosts": [
+    { "computerName": "appserver01", "checkoutRoot": "D:\\apps" }
+  ],
+  "projectNotes": [
+    "AGENTS.md - the project's own rules; they override this skill",
+    "docs/runbooks/<your-migration-runbook>.md"
+  ]
+}

package/bundles/antigravity-plugin/skills/port-to-github/references/old-host.md

@@ -0,0 +1,61 @@
+# Retiring the old host
+
+Only after: the app is on GitHub, SHA-verified, and its first GitHub deploy was green and
+verified by an artefact changing.
+
+## 1. Prove nothing is lost
+
+```powershell
+& <skill>/scripts/Compare-PortRefs.ps1 -Left <old-url> -Right https://github.com/<owner>/<repo>.git `
+    -Mode LeftInRight -LeftLabel old -RightLabel github
+```
+
+Exit 0 means every branch and tag on the old host exists on GitHub with the same SHA. If not,
+push the missing refs to GitHub first (from a fresh `git clone --mirror` of the old host, with
+an explicit refspec for just those refs) and run it again. Release tags pushed by the old CI
+after the port are the usual stragglers.
+
+## 2. Find what still depends on the old host
+
+Search every consumer's default branch (not working trees) for the old host name: dependency
+pins, registry config, CI steps, deploy scripts. Anything found keeps the old host alive, and
+keeps a credential for it alive.
+
+## 3. Choose: read-only mirror, archive, or delete
+
+| Option | When | Cost |
+|---|---|---|
+| **Read-only pull mirror of GitHub** (Actions OFF) | Something still pins from the old URL, or you want a live fallback | The old host keeps running; a mirror that stops pulling goes stale silently |
+| Archive (read-only, no sync) | Nothing depends on it; you want the old PR/issue history browsable | A frozen snapshot that drifts from day one |
+| Delete | Nothing depends on it and its history is exported | Irreversible |
+
+**Never a push mirror driven by CI.** A job pushing into a host that then runs CI on what
+arrives has caused a full outage: tests failed, deploy was skipped (not failed), the push guard
+only checked `failure`, and it pushed a change disabling the old deploy - leaving no deploy path
+anywhere. A pull mirror with Actions disabled cannot do that.
+
+## 4. Converting a Gitea repo into a pull mirror
+
+An existing Gitea repo cannot be converted in place. It must be deleted and recreated as a
+mirror under the same path, which **destroys its pull requests and issues** - export them first
+(API: `/repos/{owner}/{repo}/pulls?state=all`, `/issues?state=all`, comments per item).
+
+1. Run step 1 again immediately before, and export PRs/issues.
+2. `DELETE /api/v1/repos/{owner}/{repo}`.
+3. **Verify the delete on BOTH halves: the API returns 404 AND the repository directory is gone
+   on disk.** Gitea can remove the database row and fail on disk (a locked pack file). The next
+   create then returns 500 while still making an EMPTY mirror row, on which `mirror-sync`
+   returns 400. The Gitea log names the locked file; nothing else does.
+4. `POST /api/v1/repos/migrate` with `mirror: true`, the GitHub clone URL, and a GitHub read
+   token (`auth_token`). Then disable Actions on it (`has_actions: false`).
+5. Verify by refs, not by existence: `Compare-PortRefs.ps1 -Left <github> -Right <gitea> -Mode Equal`.
+6. If something pins from the mirror, prove it: clone the exact pinned tag from the mirror.
+
+## 5. Watching a mirror
+
+A pull mirror syncs on an interval (Gitea default 8h). A mirror behind GitHub is either LAGGING
+(the GitHub commit is newer than the mirror's last pull - normal) or STALE (the commit was there
+at the last pull and still did not arrive - the stored credential probably expired). Decide
+which by comparing the GitHub commit time with the mirror's last-update time before you touch
+any credential. `POST /repos/{owner}/{repo}/mirror-sync` forces a pull: an immediate match means
+it was lag.

package/bundles/antigravity-plugin/skills/port-to-github/scripts/Compare-PortRefs.ps1

@@ -0,0 +1,68 @@
+<#
+.SYNOPSIS
+  Compare branches and tags between two git locations by SHA. The only honest "did it copy" check.
+
+.DESCRIPTION
+  -Left and -Right can each be a URL, a local path, a UNC path or a bare repository.
+  Uses git ls-remote, so nothing is fetched or changed.
+
+  Modes:
+    Equal           every head and tag matches on both sides (after a push)
+    LeftInRight     every Left ref exists in Right with the same SHA; Right may have more
+                    (before destroying an old host: nothing on the old host may be lost)
+
+  Exit 0 when the mode holds, 1 when it does not, and the differing refs are printed.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$Left,
+    [Parameter(Mandatory)][string]$Right,
+    [ValidateSet('Equal', 'LeftInRight')][string]$Mode = 'Equal',
+    [string]$LeftLabel = 'left',
+    [string]$RightLabel = 'right',
+    [switch]$PassThru
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'PortCommon.ps1')
+
+function Get-Refs([string]$Where) {
+    $lines = Invoke-PortGit @('ls-remote', '--heads', '--tags', $Where)
+    $map = @{}
+    foreach ($l in $lines) {
+        if (-not $l) { continue }
+        $sha, $ref = $l -split "`t", 2
+        # An annotated tag shows twice: the tag object and the peeled commit (^{}). Compare the
+        # tag object; the peeled line is derived from it.
+        if ($ref -like '*^{}') { continue }
+        $map[$ref] = $sha
+    }
+    return $map
+}
+
+$l = Get-Refs $Left
+$r = Get-Refs $Right
+
+$onlyLeft = @($l.Keys | Where-Object { -not $r.ContainsKey($_) } | Sort-Object)
+$onlyRight = @($r.Keys | Where-Object { -not $l.ContainsKey($_) } | Sort-Object)
+$differ = @($l.Keys | Where-Object { $r.ContainsKey($_) -and $r[$_] -ne $l[$_] } | Sort-Object)
+
+$ok = ($onlyLeft.Count -eq 0 -and $differ.Count -eq 0)
+if ($Mode -eq 'Equal') { $ok = $ok -and ($onlyRight.Count -eq 0) }
+
+Write-Host ("{0}: {1} refs   {2}: {3} refs   only-{0}: {4}   only-{2}: {5}   differ: {6}" -f $LeftLabel, $l.Count, $RightLabel, $r.Count, $onlyLeft.Count, $onlyRight.Count, $differ.Count)
+foreach ($x in $onlyLeft) { Write-Host "  only in ${LeftLabel}:  $x" }
+if ($Mode -eq 'Equal') { foreach ($x in $onlyRight) { Write-Host "  only in ${RightLabel}: $x" } }
+foreach ($x in $differ) { Write-Host "  differs:        $x  $($l[$x].Substring(0,12)) vs $($r[$x].Substring(0,12))" }
+
+if ($l.Count -eq 0) {
+    Write-PortFail "$LeftLabel has no refs at all. An empty side cannot prove anything."
+    $ok = $false
+}
+if ($ok) { Write-PortOk "Refs agree ($Mode)." } else { Write-PortFail "Refs do NOT agree ($Mode)." }
+
+if ($PassThru) {
+    [pscustomobject]@{ Ok = $ok; OnlyLeft = $onlyLeft; OnlyRight = $onlyRight; Differ = $differ; LeftCount = $l.Count; RightCount = $r.Count }
+}
+if (-not $ok) { exit 1 }
+exit 0