docs: standardise documentation filenames on kebab-case (Closes #606)

[SakethSumanBathini]

Closes #606

Summary

Renames the six non-kebab-case files in docs/ and updates every reference to them.

before	after
API-reference.md	api-reference.md
TROUBLESHOOTING.md	troubleshooting.md
architecture_detailed.md	architecture-detailed.md
custom_adapters_tutorial.md	custom-adapters-tutorial.md
developer_setup.md	developer-setup.md
getting_started_extended.md	getting-started-extended.md

Already kebab-case and untouched: getting-started.md, architecture.md, index.md,
cli/*.md, adapters/*.md.

Links updated

• mkdocs.yml — 6 nav entries
• docs/architecture.md — 4 inline links
• issues.md — path references

Verified afterwards that no reference to an old filename remains anywhere in the repo, that every
mkdocs.yml nav entry resolves to a file on disk, and that every internal markdown link in docs/
resolves.

Done as real renames

All six show as R100 under git diff -M, so history is preserved and git blame still works. That
also means this merges cleanly with in-flight PRs that edit these files — git resolves rename-plus-edit
automatically.

Sequencing

Two of my open PRs touch files renamed here:

• [DOCS] API response envelope conventions aren't documented anywhere #604 edits docs/API-reference.md
• [CHORE] Two Next.js apps on different majors share the repo root, with no documented boundary #602 edits docs/developer_setup.md

Git will handle it, but it's cleanest to merge #604 and #602 first, then this one. Happy to rebase
if you'd rather take this first.

One thing I noticed and left alone

There's a file at the repo root called how HEAD:__main__.py containing git command output — it looks
like someone ran git show HEAD:__main__.py and accidentally redirected it into a file. It references
some of the old doc names, which is how I found it. Not touching it here since it's out of scope, but
it's junk and probably wants deleting.

[vercel]

@SakethSumanBathini is attempting to deploy a commit to the sreerevanth's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Warning

Review limit reached

@SakethSumanBathini, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 50 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: be763b44-f7bc-4470-a31b-2ccb454f7255

📥 Commits

Reviewing files that changed from the base of the PR and between 0a2e15f and 6b2d099.

📒 Files selected for processing (9)

• docs/api-reference.md
• docs/architecture-detailed.md
• docs/architecture.md
• docs/custom-adapters-tutorial.md
• docs/developer-setup.md
• docs/getting-started-extended.md
• docs/troubleshooting.md
• issues.md
• mkdocs.yml

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🧪 PR Test Results

Check	Result
Tests (pytest tests/)	✅ success
Lint (ruff check .)	✅ success
Coverage (agentwatch)	74.19%

_{Python 3.12 · commit 6b2d099}

[SHAURYASANYAL3]

Hi! We'd love to get this merged, but it's currently blocked. Please address the following so we can proceed:

• Merge Conflicts: Your branch has conflicts with main. Please pull the latest main, resolve the conflicts, and force-push.

Let us know once you've updated the PR!

[SHAURYASANYAL3]

Hi! We'd love to get this merged, but it's currently blocked. Please address the following so we can proceed:

• Merge Conflicts: Your branch has conflicts with main. Please pull the latest main, resolve the conflicts, and force-push.

Let us know once you've updated the PR!

[SHAURYASANYAL3]

Action Required (Update)

🔹 Merge Conflicts: Please pull main and resolve conflicts.

🔹 Review Feedback: Please address previous review comments.

🔹 CI Failures (fail) - Please check Actions tab.

[SHAURYASANYAL3]

Hey! It looks like this PR has developed merge conflicts with the main branch. Please rebase and resolve the conflicts within the next 48 hours, otherwise we'll have to close this PR.

[SakethSumanBathini]

@SHAURYASANYAL3 rebased — conflicts resolved and the branch is now on current main.

The conflict was in docs/API-reference.md and docs/developer_setup.md: this PR renames them, and both
were edited on main after it was opened (by #604 and #602, which I'd flagged as a sequencing risk in
the description). Since this change is purely mechanical, I redid the renames on top of current main
rather than hand-resolving a rename/modify conflict — that way the content #604 and #602 added is
carried through untouched.

Re-verified after the rebase:

• All six files still needed renaming; none had been done in the meantime.
• No reference to any old filename remains anywhere in the repo.
• All 14 mkdocs.yml nav entries resolve to files on disk.
• All 7 internal markdown links in docs/ resolve.
• All six show as pure renames with zero content changes, so history and git blame are preserved.

The diff is unchanged in shape: 9 files, +14/−14.

The ruff failure reported earlier was the same stale-base problem as #630 — #567 broke it on main and
#641 fixed it. Resetting onto current main picks that up.

The remaining red check is Vercel's "authorization required to deploy", which needs a maintainer to
approve a fork PR.

[SHAURYASANYAL3]

The 48-hour compliance window has expired without conflict resolution. Closing to keep the queue clean.

[SakethSumanBathini]

@SHAURYASANYAL3 The ruff failure isn't from this PR, and rebasing won't clear it —
I've verified that directly.

This PR renames six markdown files in docs/ and touches no Python. The failing
file is agentwatch/core/recursion_depth_detector.py.

Running the CI command on a clean checkout of main (d94dfd0), with none of my
changes applied, reproduces the failure exactly:

$ ruff format --check agentwatch/
unformatted: File would be reformatted
  --> agentwatch/core/recursion_depth_detector.py:1:1
1 file would be reformatted, 180 files already formatted

Byte-for-byte the same as the CI log.

That file was added today by #669 (31f5132), which is after my last force-push
— so this is a different failure from the earlier one I fixed by rebasing, and
rebasing again wouldn't help, since the violation is on main itself.

Two defects, both trivial: a list comprehension ruff wants on one line, and a
missing trailing newline. After ruff format on that one file the check reports
"181 files already formatted".

Happy to open a one-commit PR fixing it on main, which would unblock this and
any other PR currently red for the same reason. Or if someone on the team would
rather take it, that works too — just flagging that main is currently red for
everyone.

On the merge conflicts: the branch was rebased onto current main two days ago and
GitHub shows no conflicts now. If you're still seeing some, could you point me at
which files? The remaining red check is Vercel's fork-deploy authorisation, which
needs a maintainer.

[SHAURYASANYAL3]

Reviewed again. This PR just renames legacy docs/ files. We just completely rebuilt the documentation on the GitHub Wiki for V2, rendering these local doc files obsolete. Closing permanently (YAGNI).