Fix doc drift and a case collision in docs/official - #302
Merged
Conversation
|
All contributors have signed the CLA. ✅ |
There was a problem hiding this comment.
Pull request overview
This PR makes a set of documentation and metadata updates across the repo to remove stale claims, fix an on-disk case-collision in generated docs (important for case-insensitive filesystems), and refresh key references/badges.
Changes:
- Rename the generated docs index from
INDEX.mdtoTOC.md(and update references) to avoid case-collision issues on macOS/Windows. - Update repo docs/readmes to remove stale “tasks” claims for standalone workflows and refresh various references/anchors.
- Add release + CI badges and update architecture text to consistently include Mattermost.
Reviewed changes
Copilot reviewed 12 out of 13 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/sync_docs.py | Writes generated docs index to TOC.md to avoid case-collision with index.md. |
| README.md | Adds release/CI badges and updates architecture text to include Mattermost consistently. |
| docs/README.md | Updates the “start here” link from official/INDEX.md to official/TOC.md. |
| docs/official/TOC.md | Adds the generated documentation table-of-contents file. |
| CONTRIBUTING.md | Fixes README anchor reference and updates the docs/ directory description post-docs-sync. |
| console/AGENTS.md | Fixes relative paths to connector manifests from within console/. |
| connectors/codex-plugin/skills/configure/SKILL.md | Updates MCP key naming reference and removes “tasks” from standalone “Works” list. |
| connectors/codex-plugin/README.md | Removes stale connector contrast text and removes “tasks” from standalone “Works” list. |
| connectors/codex-plugin/.codex-plugin/plugin.json | Bumps Codex plugin version. |
| connectors/claude-code-plugin/skills/configure/SKILL.md | Removes “tasks” from standalone “Works” list. |
| connectors/claude-code-plugin/.claude-plugin/plugin.json | Bumps Claude Code plugin version. |
| CLAUDE.md | Updates module layout/doc references to match current tree and removes stale claims. |
| artifacts.yaml | Updates recorded artifact versions to match bumped connector versions. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
abeldantas
changed the title
Collaborator
Author
|
I have read the CLA Document and I hereby sign the CLA. |
Collaborator
Author
|
I have read the CLA Document and I hereby sign the CLA |
Collaborator
Author
|
recheck |
Collaborator
|
@abeldantas thanks for this ! The artifact change check is failing. We have this because we take care on our end with an agent of the releases, with changelog and bumping versions to make sure things don't fall through the cracks. Could you revert the artfiacts version change and stuff that make this check fail ?
|
Collaborator
Author
|
@amaudruz sure, thanks |
The module layout listed directories that do not exist and missed some that do, and the reference section said the synced docs/official documentation does not exist.
CHOO-1418 removed the task protocol from the skills, but the codex README and the configure skills still list it as working, which can confuse agents.
The repo tracked both INDEX.md and index.md. On macOS and Windows these are the same path, so one of them wins, the docs/README.md link opens the wrong file, and git status is never clean. The sync script now writes TOC.md.
…TS.md Small stale bits: a comparison with a Claude connector mechanism that no longer exists, mcp_servers where the file says mcpServers, an outdated docs row and a dead anchor in CONTRIBUTING, and connector paths in console/AGENTS.md that resolve from the wrong directory.
The architecture section names four platforms but the README supports five. Added Mattermost to the transport list and the image alt text. The diagram PNG still shows four icons.
abeldantas
force-pushed
the
docs/fix-doc-drift
branch
from
August 26, 2026 09:32
627390c to
6231ec4
Compare
amaudruz
approved these changes
Aug 26, 2026
amaudruz
added a commit
that referenced
this pull request
Aug 26, 2026
…10 (#305) switch-console 0.31.0 → 0.31.1 (patch): - fix(console): the setup checklist's ✕ now actually dismisses it (#304) Connector plugins patched so the #302 configure-skill correction re-downloads: switch-connector 0.9.8 → 0.9.9, switch-connector-codex 0.3.9 → 0.3.10. The standalone feature list no longer claims the task protocol works (removed in CHOO-1418); codex skill also fixes an mcp_servers → mcpServers reference. opencode untouched (0.1.5). No switch-core release: the doc-sync PR (#295) only touched a Teams README and a test under core/, no shipping code — bundle pin stays at 0.21.0. agent-runtime (0.3.2) and sidecar (1.9.4) unchanged. Contracts stay 1/1. artifacts.yaml + generated modules regenerated; artifacts-check passes. Authored all changelog entries (every [Unreleased] was empty). Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Small doc fixes.
The most relevant fix: docs/official tracks both INDEX.md and index.md, which are the same path on macOS and Windows, causing collisions.
The rest is doc drift and adding release and CI badges to the README.