Skip to content

docs: rename remote-instances.md to remote-crew.md with redirect - #12752

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
dimwael:docs/rename-remote-instances-redirect
Sep 23, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
dimwael:docs/rename-remote-instances-redirect

Conversation

@dimwael

@dimwael dimwael commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

#12697 has merged: the page's content and the instances.md naming record now say "Remote Crew", but the filename still says remote-instances. This PR is the follow-up #12697's design review asked to be filed (#12750): rename the file to match, without breaking published links. This branch is rebased on top of the merged #12697, and the renamed remote-crew.md carries #12697's content byte-for-byte; the stub and both index rows use the merged "Remote Crew" labels, so no displayed string says "Remote Instances" anywhere in the diff.

Why it matters

The filename is the page's address: it is what index.md and README.md link to and what external links (GitHub blob URLs) point at. Left unrenamed, the feature's page permanently carries the retired name.

What changed (motivation → approach → change)

Goal: rename the file without breaking any existing link to it.

Mechanism check first, as the issue asks: this repository has no docs site generator — no mkdocs/docusaurus/sphinx config anywhere, and .github/workflows/pages.yml publishes only the marketing site in site/. These docs ship inside the Python package (read in-app; the tips catalog scans them) and are linked externally as GitHub blob URLs (e.g. from cli_doctor.py and the settings panels). Neither surface has a redirect facility, and git log --diff-filter=R shows no prior doc rename to follow as precedent. So this PR uses the fallback the issue sanctions:

  • git mv src/kiro_crew/docs/remote-instances.md src/kiro_crew/docs/remote-crew.md (rename detected, history follows).
  • A stub page at the old path pointing to the new one, so existing links land on a pointer instead of a 404. Tradeoff stated per the issue: a stub is not a true redirect — a reader arriving at the old URL must click through once, and the old path keeps existing as a file. With markdown served from a repository and a package, that is the strongest redirect available.
  • Referring links updated: index.md (two rows) and README.md now target remote-crew.md; the README row also links the stub so it stays reachable from the directory index (docs-lint's reachability gate).
  • test/test_remote_instances_doc.py → test/test_remote_crew_doc.py, with its pinned DOC path and docstring updated — the rename the issue calls reasonable in the same change.

Deliberately untouched, per the issue: page content (that is #12697's job — it is still open and touches this file, so whichever lands second rebases; git's rename detection carries content edits into the new filename), the test/gui_user scenario slug remote-instances (a stored identifier, not displayed copy), and the wider backend "instance" vocabulary (instances.json, apps.mochi.instances.*, backend keys and routes).

Backwards compatibility

Compatible: every existing link to src/kiro_crew/docs/remote-instances.md still resolves — the old path now holds a stub that points at the new page. In-repo referrers were swept (git grep -n "remote-instances"): all doc links updated here; the remaining matches are the gui_user slug (stored identifier, out of scope per the issue) and a code comment in website/electron/mochi/pet-preload.js that refers to a panelBridge code note, not this file.

Tests

test/test_remote_crew_doc.py (renamed from test_remote_instances_doc.py) keeps pinning the page's code-coupled claims, now at the new path — all 11 tests pass locally. ./scripts/docs-lint.sh passes: it validates that every link resolves (old references would fail it) and that both the renamed page and the stub are reachable from the directory index.

Manual verification

Verified the stub's link and both index links resolve relative to src/kiro_crew/docs/ (same directory, checked by docs-lint's link resolution), the renamed page's own relative links (../../../docs/guides/...) are unaffected since the file stays in the same directory, and git log --follow traces the renamed file's history back through #12581.

Related Issues

Fixes #12750

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

@dimwael
dimwael requested review from a team and pepmach September 22, 2026 08:28
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 22, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 22, 2026
@dimwael
dimwael force-pushed the docs/rename-remote-instances-redirect branch from c265e37 to cda40f9 Compare September 22, 2026 08:53
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 22, 2026
@dimwael

dimwael commented Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

CI status — one infra flake, zero findings against the diff:

  • Focus Cue Gate crashed in its own self-test, before examining any change: check_focus_cue.py:805's tempfile.TemporaryDirectory() cleanup raced and threw OSError: [Errno 39] Directory not empty: '/tmp/.../r/.git/objects' (log). This diff touches no UI (docs + one test file).
  • Await Fast Gate and Coverage Gate are cascade: Await Fast Gate fails closed because the Fast Gate run concluded failure, and Coverage Gate fails closed because the heavy jobs were skipped on purpose.
  • Everything else is green, including Docs Lint and all backend/frontend test shards on the previous round (the first round's Backend Lint red was a runner shutdown, exit 143; black --check/flake8/isort pass locally on the touched file).

A re-run of the Fast Gate workflow should clear all three. The four fork review workflows are also awaiting maintainer approval. Nothing on my side to change; happy to rebase-retrigger if main moves first.

@dimwael
dimwael force-pushed the docs/rename-remote-instances-redirect branch from cda40f9 to a4a6e1a Compare September 22, 2026 12:17
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 22, 2026
@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed f276afe2c8e555be44ef02c1e2e7895cc49b9018 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] f276afe

@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of f276afe2c8e555be44ef02c1e2e7895cc49b9018 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] f276afe

@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed f276afe2c8e555be44ef02c1e2e7895cc49b9018 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] f276afe

@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of f276afe2c8e555be44ef02c1e2e7895cc49b9018 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify issue #12750's text sanctions the stub fallback and the identifier exclusions — every other claim checks out against the base tree.

What this change ships

Inventory (5 items) — 5 justified

Intent: FIX — finish merged #12697's rename so the Remote Crew page's filename matches its name, without breaking published links (follow-up issue #12750).

  1. The Remote Crew page now lives at remote-crew.md, content byte-identical (same blob hash fc538008f) — justified
  2. Old address remote-instances.md becomes an 8-line stub; a reader arriving there clicks through once — justified
  3. Both index.md rows and the README.md row now link the new path — justified
  4. README row gains "Formerly remote-instances.md" text linking the stub — justified
  5. test_remote_instances_doc.py renamed to test_remote_crew_doc.py; only the pinned path and docstring change — justified

Checks run: remote-instances grep leaves only stored identifiers (gui_user slug, locale keys, a pet-preload.js comment) — no code links the filename; no mkdocs/docusaurus/sphinx config exists, so a stub is the only redirect; scripts/docs_lint.py enforces the index-reachability rule item 4 satisfies; description's "#12697 … still open" sentence is stale but harmless — the base carries the merged content.

[FIRST-PRINCIPLES-REVIEWED] f276afe

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 22, 2026
@dimwael

dimwael commented Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

First Principles BLOCK acknowledged — it is an ordering dependency, not a defect in this diff: the lane reads the base spec (docs/system-specs/modules/instances.md:9-21), which still records "Remote Crew" as retired because #12697 (which flips that record and the page's displayed names) has not merged yet. This PR is exactly the follow-up #12697's design review asked to be filed as #12750.

Per the lane's own clear condition: once #12697 merges, I will rebase this branch onto main so the run reads the merged naming record — the content edits #12697 makes to remote-instances.md will carry into remote-crew.md via git rename detection. PR description updated to state the sequencing. All other lanes are green on a4a6e1a1c (Fast Gate, Docs Lint, all backend/frontend shards, builds — last round's Focus-Cue temp-dir flake cleared on rerun).

Note for maintainers: #12697 currently shows merge conflicts against main and needs a rebase on its side first.

@dimwael
dimwael force-pushed the docs/rename-remote-instances-redirect branch from a4a6e1a to 303740c Compare September 22, 2026 15:25
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 22, 2026
@dimwael
dimwael force-pushed the docs/rename-remote-instances-redirect branch from 303740c to 932a259 Compare September 22, 2026 16:20
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 22, 2026
@dimwael

dimwael commented Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

This round's backend reds are main breakage, not this diff: test_mcp_debug.py's 501-relay pin fails deterministically on current main (both Linux and Windows shard 1) because #12745 landed diag after #12731 pinned the routes to 501-until-diag-lands — filed as #12852 with repro. This PR is docs-only and touches neither file (verified: the test fails identically on pure origin/main in a clean worktree).

Meanwhile all four AI review lanes are green on this diff (First Principles flipped BLOCK→PASS after rebasing onto the merged #12697, per its stated clear condition), Docs Lint passes, and the earlier Windows flakes (#12685 port-identity, #12359 runtime-cleanup) rotated out this round. I'll rebase once #12852 is fixed on main.

@dimwael
dimwael force-pushed the docs/rename-remote-instances-redirect branch from 932a259 to 4f0d0f2 Compare September 22, 2026 17:16
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 22, 2026
@dimwael
dimwael force-pushed the docs/rename-remote-instances-redirect branch from 4f0d0f2 to 98d3fcb Compare September 22, 2026 18:10
The Remote Crew feature's page kept its remote-instances filename after
the kirodotdev#12697 vocabulary pass because the filename is a published URL.
Rename it to remote-crew.md and leave a stub at the old path so existing
links keep resolving.

There is no docs site generator in this repository — these pages ship
inside the Python package and are linked externally as GitHub blob URLs
— so no true redirect mechanism exists; the stub page is the fallback
the issue sanctions for that case.

Referring links in index.md and README.md now target remote-crew.md,
and test_remote_instances_doc.py moves to test_remote_crew_doc.py with
its pinned path updated. The test/gui_user scenario slug and backend
'instance' vocabulary are deliberately untouched.

Fixes kirodotdev#12750
@dimwael
dimwael force-pushed the docs/rename-remote-instances-redirect branch from 98d3fcb to f276afe Compare September 22, 2026 19:09
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 22, 2026
@iamwhatever
iamwhatever enabled auto-merge (squash) September 23, 2026 01:28
@iamwhatever
iamwhatever merged commit 82b1411 into kirodotdev:main Sep 23, 2026
96 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 23, 2026
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
…odotdev#12752)

The Remote Crew feature's page kept its remote-instances filename after
the kirodotdev#12697 vocabulary pass because the filename is a published URL.
Rename it to remote-crew.md and leave a stub at the old path so existing
links keep resolving.

There is no docs site generator in this repository — these pages ship
inside the Python package and are linked externally as GitHub blob URLs
— so no true redirect mechanism exists; the stub page is the fallback
the issue sanctions for that case.

Referring links in index.md and README.md now target remote-crew.md,
and test_remote_instances_doc.py moves to test_remote_crew_doc.py with
its pinned path updated. The test/gui_user scenario slug and backend
'instance' vocabulary are deliberately untouched.

Fixes kirodotdev#12750

Co-authored-by: Wael Dimassi <ydimawae@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: rename remote-instances.md to remote-crew.md with a redirect

2 participants