chore/prod-readiness — repo cleanup (Group 1 of release/jsr-readiness)

.agents/skills/openhands-handoff/SKILL.md

@@ -39,9 +39,100 @@ required summary artifacts keep local and cloud agents synchronized.
 | Thread replies   | Optional `OPENHANDS_REPLIES_PATH` review-comment replies.                                      |
 | Chainable token  | `PAT_TOKEN` or GitHub App token; required for cloud-created events to trigger more workflows.   |
 
+## Trigger Syntax
+
+Use one of these from GitHub mobile, a local agent, or another cloud agent:
+
+- Add `fix-me` or `openhands` to an issue or PR.
+- Add a model label: `agent:sonnet`, `agent:gpt`, or `agent:gemini`.
+- Comment with `@openhands-agent ...` from an owner, member, or collaborator account.
+- Push a commit whose message contains `[openhands ...]`.
+- Run `OpenHands Agent` manually from Actions.
+
+Model selection is per run:
+
+```text
+@openhands-agent model=anthropic/claude-sonnet-4 use harness proceed to IMPL-EVAL
+@openhands-agent agent=gemini output=respond-comments fix the legitimate Augment comments
+[openhands model=openai/gpt-5.1 output=pr-comment] run a focused evaluator pass
+@openhands-agent provider=openrouter model=openai/gpt-5.1 run through OpenRouter
+```
+
+The model precedence is:
+
+1. manual workflow `model` input,
+2. `model=...` in a comment or commit message,
+3. `agent=<profile>` in a comment or commit message,
+4. `agent:<profile-or-literal>` label,
+5. repository variable `OPENHANDS_DEFAULT_MODEL`,
+6. `anthropic/claude-sonnet-4`.
+
+The workflow infers the provider from the selected model prefix unless `provider=...` is present.
+
+| Model prefix           | Provider     | Preferred secret         |
+| ---------------------- | ------------ | ------------------------ |
+| `anthropic/`           | `ANTHROPIC`  | `LLM_API_KEY_ANTHROPIC`  |
+| `openai/`              | `OPENAI`     | `LLM_API_KEY_OPENAI`     |
+| `gemini/` or `google/` | `GEMINI`     | `LLM_API_KEY_GEMINI`     |
+| `openrouter/`          | `OPENROUTER` | `LLM_API_KEY_OPENROUTER` |
+
+Provider-specific secrets fall back to `LLM_API_KEY` when the specific key is absent. Optional
+provider-specific base URLs use the same suffix pattern, such as `LLM_BASE_URL_OPENROUTER`, with
+`LLM_BASE_URL` as the fallback.
+
+## Output Modes
+
+| Mode               | Behavior                                                                                |
+| ------------------ | --------------------------------------------------------------------------------------- |
+| `pr-comment`       | Post one summary comment to the target issue or PR.                                     |
+| `respond-comments` | Post one summary comment that explicitly responds to relevant review or issue comments. |
+| `thread-replies`   | Post the summary and any review-thread replies from `OPENHANDS_REPLIES_PATH`.           |
+| `summary-only`     | Upload artifacts only; do not comment.                                                  |
+
+The agent must write `OPENHANDS_SUMMARY_PATH` before exit. The workflow gives each run a fresh
+`OPENHANDS_RUN_DIR` outside the repository checkout and mirrors compact trace metadata to
+`OPENHANDS_TRACE_DIR`, usually under `.llm/tmp/run/openhands/<source>/run-<id>-<attempt>/`.
+Do not write or reuse `.llm/tmp/openhands/summary.md`; that legacy shared path is ignored to avoid
+posting stale summaries from old PR branches.
+
+The workflow owns GitHub comments: it reacts to the trigger comment, posts one running status
+comment with the Actions URL, then edits that same comment with the final summary. Agents should not
+post their own PR or issue comments during OpenHands runs.
+
+## Token Rule
+
+GitHub does not trigger follow-up workflows from events created with the default `GITHUB_TOKEN`. Use
+a dedicated bot PAT or GitHub App token in `PAT_TOKEN` when cloud-emitted commits, comments, or
+labels should trigger another workflow.
+
+Local agents that push with your own credentials already produce chainable events.
+
+## Review Comment Workflow
+
+For Augment or Copilot review comments:
+
+1. Trigger with `@openhands-agent output=respond-comments ...` or `output=thread-replies`.
+2. The workflow writes current issue comments to `OPENHANDS_ISSUE_COMMENTS_PATH`.
+3. For PRs, the workflow writes review comments to `OPENHANDS_PR_REVIEW_COMMENTS_PATH`.
+4. The agent fixes legitimate comments first when the prompt asks for that.
+5. The final summary names each addressed comment and the validation result.
+
+Use `thread-replies` only when the agent can map a response to exact PR review-comment IDs.
+
+## Long-Running VPS Sessions
+
+Use `ops/openhands/docker-compose.yml` for the Dokploy deployment. The VPS session is for multi-step
+work that needs the OpenHands Web UI, pause/resume, or a human-in-the-loop checkpoint.
+
+Recommended split:
+
+- Actions workflow: short PR/issue fixups, evaluator passes, small research tasks, mobile triggers.
+- VPS Web UI/SDK session: long-running implementation, planning with checkpoints, or work requiring
+  human review before continuing.
+
 ## Workflow
 
-1. Read `AGENTS-handoff.md` for trigger syntax and token rules.
+1. Use the trigger syntax and token rules in this skill.
 2. If the prompt says `use harness`, load `netscript-harness` and follow its evaluator separation.
 3. Choose the smallest trigger:
    - add `fix-me` or `openhands` for default model work,
@@ -84,7 +175,7 @@ required summary artifacts keep local and cloud agents synchronized.
 
 | File                                     | Load when                                  |
 | ---------------------------------------- | ------------------------------------------ |
-| `AGENTS-handoff.md`                      | Any OpenHands trigger or handoff task      |
+| `.agents/skills/openhands-handoff/SKILL.md` | Any OpenHands trigger or handoff task   |
 | `.github/workflows/openhands-agent.yml`  | Debugging or changing the Actions workflow |
 | `.openhands/setup.sh`                    | Adjusting cloud bootstrap/toolchain setup  |
 | `.openhands/microagents/repo.md`         | Updating OpenHands repo context            |

.claude/skills/openhands-handoff/SKILL.md

@@ -39,9 +39,100 @@ required summary artifacts keep local and cloud agents synchronized.
 | Thread replies   | Optional `OPENHANDS_REPLIES_PATH` review-comment replies.                                      |
 | Chainable token  | `PAT_TOKEN` or GitHub App token; required for cloud-created events to trigger more workflows.   |
 
+## Trigger Syntax
+
+Use one of these from GitHub mobile, a local agent, or another cloud agent:
+
+- Add `fix-me` or `openhands` to an issue or PR.
+- Add a model label: `agent:sonnet`, `agent:gpt`, or `agent:gemini`.
+- Comment with `@openhands-agent ...` from an owner, member, or collaborator account.
+- Push a commit whose message contains `[openhands ...]`.
+- Run `OpenHands Agent` manually from Actions.
+
+Model selection is per run:
+
+```text
+@openhands-agent model=anthropic/claude-sonnet-4 use harness proceed to IMPL-EVAL
+@openhands-agent agent=gemini output=respond-comments fix the legitimate Augment comments
+[openhands model=openai/gpt-5.1 output=pr-comment] run a focused evaluator pass
+@openhands-agent provider=openrouter model=openai/gpt-5.1 run through OpenRouter
+```
+
+The model precedence is:
+
+1. manual workflow `model` input,
+2. `model=...` in a comment or commit message,
+3. `agent=<profile>` in a comment or commit message,
+4. `agent:<profile-or-literal>` label,
+5. repository variable `OPENHANDS_DEFAULT_MODEL`,
+6. `anthropic/claude-sonnet-4`.
+
+The workflow infers the provider from the selected model prefix unless `provider=...` is present.
+
+| Model prefix           | Provider     | Preferred secret         |
+| ---------------------- | ------------ | ------------------------ |
+| `anthropic/`           | `ANTHROPIC`  | `LLM_API_KEY_ANTHROPIC`  |
+| `openai/`              | `OPENAI`     | `LLM_API_KEY_OPENAI`     |
+| `gemini/` or `google/` | `GEMINI`     | `LLM_API_KEY_GEMINI`     |
+| `openrouter/`          | `OPENROUTER` | `LLM_API_KEY_OPENROUTER` |
+
+Provider-specific secrets fall back to `LLM_API_KEY` when the specific key is absent. Optional
+provider-specific base URLs use the same suffix pattern, such as `LLM_BASE_URL_OPENROUTER`, with
+`LLM_BASE_URL` as the fallback.
+
+## Output Modes
+
+| Mode               | Behavior                                                                                |
+| ------------------ | --------------------------------------------------------------------------------------- |
+| `pr-comment`       | Post one summary comment to the target issue or PR.                                     |
+| `respond-comments` | Post one summary comment that explicitly responds to relevant review or issue comments. |
+| `thread-replies`   | Post the summary and any review-thread replies from `OPENHANDS_REPLIES_PATH`.           |
+| `summary-only`     | Upload artifacts only; do not comment.                                                  |
+
+The agent must write `OPENHANDS_SUMMARY_PATH` before exit. The workflow gives each run a fresh
+`OPENHANDS_RUN_DIR` outside the repository checkout and mirrors compact trace metadata to
+`OPENHANDS_TRACE_DIR`, usually under `.llm/tmp/run/openhands/<source>/run-<id>-<attempt>/`.
+Do not write or reuse `.llm/tmp/openhands/summary.md`; that legacy shared path is ignored to avoid
+posting stale summaries from old PR branches.
+
+The workflow owns GitHub comments: it reacts to the trigger comment, posts one running status
+comment with the Actions URL, then edits that same comment with the final summary. Agents should not
+post their own PR or issue comments during OpenHands runs.
+
+## Token Rule
+
+GitHub does not trigger follow-up workflows from events created with the default `GITHUB_TOKEN`. Use
+a dedicated bot PAT or GitHub App token in `PAT_TOKEN` when cloud-emitted commits, comments, or
+labels should trigger another workflow.
+
+Local agents that push with your own credentials already produce chainable events.
+
+## Review Comment Workflow
+
+For Augment or Copilot review comments:
+
+1. Trigger with `@openhands-agent output=respond-comments ...` or `output=thread-replies`.
+2. The workflow writes current issue comments to `OPENHANDS_ISSUE_COMMENTS_PATH`.
+3. For PRs, the workflow writes review comments to `OPENHANDS_PR_REVIEW_COMMENTS_PATH`.
+4. The agent fixes legitimate comments first when the prompt asks for that.
+5. The final summary names each addressed comment and the validation result.
+
+Use `thread-replies` only when the agent can map a response to exact PR review-comment IDs.
+
+## Long-Running VPS Sessions
+
+Use `ops/openhands/docker-compose.yml` for the Dokploy deployment. The VPS session is for multi-step
+work that needs the OpenHands Web UI, pause/resume, or a human-in-the-loop checkpoint.
+
+Recommended split:
+
+- Actions workflow: short PR/issue fixups, evaluator passes, small research tasks, mobile triggers.
+- VPS Web UI/SDK session: long-running implementation, planning with checkpoints, or work requiring
+  human review before continuing.
+
 ## Workflow
 
-1. Read `AGENTS-handoff.md` for trigger syntax and token rules.
+1. Use the trigger syntax and token rules in this skill.
 2. If the prompt says `use harness`, load `netscript-harness` and follow its evaluator separation.
 3. Choose the smallest trigger:
    - add `fix-me` or `openhands` for default model work,
@@ -84,7 +175,7 @@ required summary artifacts keep local and cloud agents synchronized.
 
 | File                                     | Load when                                  |
 | ---------------------------------------- | ------------------------------------------ |
-| `AGENTS-handoff.md`                      | Any OpenHands trigger or handoff task      |
+| `.agents/skills/openhands-handoff/SKILL.md` | Any OpenHands trigger or handoff task   |
 | `.github/workflows/openhands-agent.yml`  | Debugging or changing the Actions workflow |
 | `.openhands/setup.sh`                    | Adjusting cloud bootstrap/toolchain setup  |
 | `.openhands/microagents/repo.md`         | Updating OpenHands repo context            |

.llm/harness/debt/arch-debt.md

@@ -720,3 +720,37 @@ Seeded from
   and green validation.
 - **Gate:** `deno task deps:latest --behind-only --pretty` returns only documented holds, then
   targeted package checks and `deno task publish:dry-run` pass after each migration.
+
+## packages/cli + packages/service — legacy connection-string env alias (`database-connectivity-legacy-connstring-alias`)
+
+- **Reason:** The servy/env-file generators emit a `ConnectionStrings__{provider}db` env var labelled
+  a "legacy alias" (`packages/cli/src/kernel/adapters/windows/servy/servy-environment.ts:139`,
+  `env-file-values.ts:130`, `env-file-content.ts:98`). It is **not** back-compat cruft: it is a live
+  runtime contract **read** by `@netscript/service` DB diagnostics
+  (`packages/service/src/diagnostics/database-connectivity.ts:48,71,94` —
+  `ConnectionStrings__mysqldb`/`postgresdb`/`mssqldb`). The `chore/prod-readiness` cleanup classifies
+  it FUNCTIONAL / OFF-LIMITS (F3) and records it here rather than removing it.
+- **Owner:** CLI env-generation + `@netscript/service` diagnostics maintainers.
+- **Target:** Consolidate the `{provider}db` alias and its reader onto a single canonical
+  `ConnectionStrings__{resource}` form once the env-var contract is unified; out of cleanup scope.
+- **Linked plan:** `.llm/tmp/run/chore-prod-readiness--cleanup/plan.md` (PR-5, F3);
+  `.llm/tmp/run/chore-prod-readiness--cleanup/research.md` (F3 row + open-questions).
+- **Created:** 2026-06-18 (PLAN-EVAL cycle-1 finding).
+- **Status:** open, DEBT_ACCEPTED. Removing the alias would break DB connectivity diagnostics.
+- **Gate:** grep parity between the writers above and the `connStringEnv` readers in
+  `database-connectivity.ts`; close when both sides move to a single canonical key.
+
+## packages/database — MySQL JSON extension alias removal deferred (`mysqljsonextension-deprecated-removal-deferred`)
+
+- **Reason:** `mysqlJsonExtension` was a public alias for `sqlJsonExtension` without an existing
+  `@deprecated` marker. The `chore/prod-readiness` cleanup follows deprecate-before-remove for
+  public symbols, so this run marks the alias deprecated and defers physical removal.
+- **Owner:** `@netscript/database` maintainers.
+- **Target:** Remove `mysqlJsonExtension` in a later post-alpha cleanup after the deprecation marker
+  has shipped.
+- **Linked plan:** `.llm/tmp/run/chore-prod-readiness--cleanup/plan.md` (PR-7, G1-3b);
+  `.llm/tmp/run/chore-prod-readiness--cleanup/research.md` (S4/S4′).
+- **Created:** 2026-06-18 (G1-3b implementation).
+- **Status:** open, DEBT_ACCEPTED. Removal is intentionally deferred.
+- **Gate:** consumer scan for `mysqlJsonExtension` across packages, plugins, scaffold templates,
+  docs, ops, and `.llm/tools/`; remove only when zero live consumers remain.

.llm/harness/workflow/agent-handoff.md

@@ -23,7 +23,7 @@ Preferred triggers:
 - commit message `[openhands model=<provider/model> output=<mode>] ...`,
 - manual `OpenHands Agent` workflow dispatch.
 
-The canonical details live in `AGENTS-handoff.md` and `.agents/skills/openhands-handoff/SKILL.md`.
+The canonical details live in `.agents/skills/openhands-handoff/SKILL.md`.
 
 ## Harness Rules