ombi-mcp/docs/megaplans/m1/01-tool-namespace-catalogue.md

Phase 01 — Tool Namespace & Catalogue Realignment

Objective

Eliminate the ombi_* prefix across all 31 tools; enforce read_* for the 14 read-only tools and write_* for the 17 mutating tools. Bundles remain policy groups, not name segments.

Prerequisites

• Phase 00 complete (this file and the index exist).
• Source documents to mutate: docs/schema/02-tool-mapping.md, docs/schema/03-input-schemas.md, docs/schema/04-results.md, docs/schema/05-endpoint-coverage.md, docs/schema/06-verification.md, docs/schema/07-settings-types.md, docs/schema/README.md, AGENTS.md (name-convention line only).

Specification

Complete rename / bundle / annotation matrix (the authoritative table)

Annotations are carried over unchanged per tool (conservative rules from the existing spec: all writes idempotentHint:false, everything openWorldHint:true).

Old name	New name	Bundle	readOnlyHint	destructiveHint	idempotentHint	Result families
ombi_search	read_search	core	true	false	true	media_page
ombi_discover	read_discover	core	true	false	true	media_page
ombi_media	read_media	core	true	false	true	media_page
ombi_reference	read_reference	core	true	false	true	reference_page
ombi_requests	read_requests	core	true	false	true	request_page, retry_page
ombi_request_stats	read_request_stats	core	true	false	true	metrics
ombi_issues	read_issues	core	true	false	true	issue_page, comment_page, group_page, metrics
ombi_votes	read_votes	core	true	false	true	vote_page
ombi_users	read_users	core	true	false	true	user_page, reference_page
ombi_library	read_library	core	true	false	true	media_page, calendar_page, artwork_page
ombi_server	read_server	core	true	false	true	metrics, reference_page
ombi_integration_read	read_integration	core	true	false	true	reference_page, user_page
ombi_request_create	write_request_create	core	false	false	false	mutation
ombi_request_subscribe	write_request_subscribe	core	false	false	false	mutation
ombi_issue_create	write_issue_create	core	false	false	false	mutation
ombi_issue_comment	write_issue_comment	core	false	false	false	mutation
ombi_vote	write_vote	core	false	false	false	mutation
ombi_user_preferences	write_user_preferences	core	false	false	false	mutation
ombi_request_moderate	write_request_moderate	moderation	false	true	false	mutation
ombi_request_delete	write_request_delete	moderation	false	true	false	mutation
ombi_request_options	write_request_options	moderation	false	true	false	mutation
ombi_request_reprocess	write_request_reprocess	moderation	false	true	false	mutation
ombi_issue_manage	write_issue_manage	moderation	false	true	false	mutation
ombi_settings_read	read_settings	administration	true	false	true	settings
ombi_settings_write	write_settings_patch	administration	false	true	false	mutation
ombi_user_manage	write_user_manage	administration	false	true	false	mutation
ombi_integration_test	write_integration_test	administration	false	false	false	mutation
ombi_job_run	write_job_run	administration	false	true	false	mutation
ombi_notification_send	write_notification_send	administration	false	false	false	mutation
ombi_retry_remove	write_retry_remove	administration	false	true	false	mutation
ombi_logs	read_logs	administration	true	false	true	logs

Counts check: 31 rows; read_* = 14; write_* = 17; core = 18; moderation = 5; administration = 8.

Rename application rules

1. Replace every occurrence of each old tool name across 02-tool-mapping.md, 03-input-schemas.md, 04-results.md, 05-endpoint-coverage.md, 06-verification.md, 07-settings-types.md, README.md — including prose ("ombi_search.text routes to…"), the catalogue table, the annotations table (03-input-schemas.md lines 7–39), the ledger Owner / branch column, and the verification examples.
2. Rewrite the annotations table in 03-input-schemas.md header block with the new names and identical flags (matrix above).
3. Update operation enum values in the output envelope to the 31 new names (Phase 05 owns the restructure; Phase 01 owns the enum values).
4. Update section headers in 03-input-schemas.md (## ombi_search → ## read_search, etc.) keeping the same tool order.
5. Branch descriptors keep tool / branch notation in the ledger with the new tool name (e.g. read_media / by_request, write_settings_patch / patch:ombi).
6. README wording updates: "The catalogue defines 31 tools: 18 core, 5 moderation and 8 administration" stays; add "Tool names encode effect: read_* = read-only, write_* = state-mutating. Bundles are deployment policy groups, not prefixes."
7. AGENTS.md convention line "MCP tool names should be snake_case and prefixed consistently (e.g. ombi_search, ombi_request)" → replaced with the read_*/write_* convention.

Target artefacts

• docs/schema/02-tool-mapping.md — all ombi_* tool-name occurrences renamed (prose, routing tables, inline mentions).
• docs/schema/03-input-schemas.md — annotations table rewritten with new names; all 31 ## section headers renamed, order preserved.
• docs/schema/04-results.md — operation enum values updated to the 31 new names; tool-name mentions in prose renamed.
• docs/schema/05-endpoint-coverage.md — Owner / branch column tool names renamed.
• docs/schema/06-verification.md — all tool-name occurrences in examples and text renamed.
• docs/schema/07-settings-types.md — ombi_settings_read/ombi_settings_write → read_settings/write_settings_patch.
• docs/schema/README.md — catalogue wording updated per rule 6.
• AGENTS.md — naming-convention line updated per rule 7.

Verification gates

• grep -rn "ombi_" docs/schema/ returns zero tool-name matches (any remaining ombi_ strings — e.g. ombi_movie/ombi_tv_parent/ombi_tv_child/ombi_album inside the identifier.namespace enum — are ID namespaces, not tool names, and are allowed).
• Every read_* tool has readOnlyHint:true; every write_* has readOnlyHint:false; flag matrix identical to the table above.
• Bundle counts unchanged: 18/5/8.

Evidence labels

• Documented — annotation flags (readOnlyHint/destructiveHint/idempotentHint/openWorldHint) carry over unchanged from the existing specification; this phase introduces no new flag semantics.
• Design — the read_*/write_* prefix split and the bundle-as-policy-group rule are intentional MCP contract decisions (Megaplan decision context).
• Verify — none introduced by this phase.