plan · supabase_json

Oro Docs MCP plan

plan artifact · for Oro Docs MCP · status approved

Planning Surface

Use this to decide what happens next.

Status

approved

open questions

id	owner	blocks	status	question
OQ-PLAN-001	justin	- M-00.T1 - M-01.T1	open	Approve M-00 only, or approve M-00 plus M-01 for local implementation?

Agent Handoff

Start Here

plan artifact · for Oro Docs MCP · status approved

Completion Evidence

No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.

Open Questions

OQ-PLAN-001: id: string, owner: string, blocks: object, status: string, question: string

Structured Payload

Machine-readable source fields

git

repo url

https://github.com/justinb2bea/oro-docs-mcp.git

pr policy

optional

merge policy

manual

branch prefix

feature/oro-docs-mcp-

commit policy

required

worktree root

/opt/redk3y/apps/oro-docs-mcp

default base branch

main

clean workspace required

false

gates

id	name	type	depends on	return path	blocks dispatch
GATE-001	Exec Build Approval	exec	- PLAN.json	task_planning	true
GATE-002	Filesystem Safety Review	reviewer	- M-02	architecture	false

modules

id	goal	name	risks	tasks	status
M-00	Confirm package location, docs source path, runtime, and registration target before implementation.	Substrate Confirmation	- RISK-M00-001: Wrong package location could mix RedKey, Oro docs, and MCP implementation ownership.	- Audit Oro Docs MCP Substrate: git: object, role: string, brief: string, title: string, output: object, dispatch: object, local_id: string, acceptance: object, agent_hint: string, depends_on: object, hard_stops: object, files_owned: object	complete
M-01	Create MCP package, index Oro docs, and expose `search_oro`.	Indexer and Search Tool	- RISK-M01-001: RST parsing can become a blocker.	- Build Oro Docs Indexer and Search MCP Tool: git: object, role: string, brief: string, title: string, output: object, dispatch: object, local_id: string, acceptance: object, agent_hint: string, depends_on: object, hard_stops: object, files_owned: object	approved
M-02	Add `query_docs_filesystem_oro` with safe read/list/search commands.	Read-Only Docs Filesystem Tool	- RISK-M02-001: Filesystem boundary bugs are high impact.		approved
M-03	Add optional embeddings and hybrid retrieval while preserving keyword-only fallback.	Semantic and Hybrid Search	- RISK-M03-001: Semantic retrieval can obscure exact matches.		approved
M-04	Index selected Oro application source files as a separate, filterable corpus.	Oro Application Source Corpus	- RISK-M04-001: Source results can dominate official docs answers.		approved
M-05	Add MCP cards and browser-readable catalog content for `mcp.bezeliq.ai`.	MCP Cards and Browser Catalog	- RISK-M05-001: Catalog could expose implementation details or secrets.		approved
M-06	Add quality, regression, and safety tests for the complete MCP.	Evaluation Harness	- RISK-M06-001: Evaluation can be too shallow to catch bad retrieval.		approved
M-07	Deploy the registry root and Oro MCP endpoint to `mcp.bezeliq.ai`.	Hosted Deployment			approved
M-08	Document and wire the complete MCP into local Codex/Atlas configuration.	Registration and Smoke Tests			approved

project

oro-docs-mcp

name

Oro Documentation MCP

status

approved

deadline

No value captured.

client id

redkey

source artifacts

decomp

docs/projects/oro-docs-mcp/artifacts/DECOMP.json

intent

docs/projects/oro-docs-mcp/artifacts/INTENT.json

policy

No value captured.

ux spec

No value captured.

research

No value captured.

architecture

docs/projects/oro-docs-mcp/artifacts/ARCHITECTURE.json

requirements

docs/projects/oro-docs-mcp/artifacts/REQUIREMENTS.json

intake triage

docs/projects/oro-docs-mcp/artifacts/INTAKE_TRIAGE.json

coherence review

docs/projects/oro-docs-mcp/artifacts/COHERENCE_REVIEW.json

dev studio

views

summary
module_board
dependency_graph
task_table
context_packets
gates
risks
open_questions
completion_contracts

render as

project_plan

open questions

id	owner	blocks	status	question
OQ-PLAN-001	justin	- M-00.T1 - M-01.T1	open	Approve M-00 only, or approve M-00 plus M-01 for local implementation?

schema version

1.0

dependency graph

root tasks

M-00.T1

critical path

M-00.T1
M-01.T1
M-02
M-03
M-04
M-05
M-06
M-07
M-08

terminal tasks

M-08

parallel groups

No items captured.

planning summary

goal

Build a complete hosted BezelIQ MCP registry at mcp.bezeliq.ai with an Oro MCP at /oro: docs search, exact docs inspection, semantic/hybrid retrieval, application-source corpus, browser catalog, MCP cards, registration, and evaluation.

must show

search_oro returns useful docs results for Oro concepts.
query_docs_filesystem_oro can inspect exact .rst files and search the docs tree.
Hybrid search works when embeddings are configured and degrades to keyword search otherwise.
Oro application source is indexed as a separate filterable corpus.
mcp.bezeliq.ai explains available MCPs, how to use them, and the tools they expose for browser visitors.
mcp.bezeliq.ai/oro exposes or documents the Oro MCP endpoint.
The index can be rebuilt from the local Oro docs checkout.
Unsafe filesystem commands and path traversal are rejected.

out of scope

Visual UI.
Public hosting.
Changing Oro docs.
Embedding-only retrieval with no exact keyword fallback.
Unfiltered indexing of vendor/cache/generated/secret-prone source paths.

global hard stops

If path confinement cannot be verified, stop before exposing filesystem query tool.
If MCP config would require moving Oro docs inside RedKey, return to architecture.
If core keyword/docs filesystem features require secrets or paid APIs, return to architecture.

global constraints

Oro repos remain outside RedKey as sibling checkouts.
The Projects database is the registry database for MCP server/card/status/refresh metadata.
Keyword search and filesystem tools work offline without paid API calls.
Semantic search is enabled only when embedding credentials are configured.
Runtime docs access is read-only.
No build dispatch or MCP implementation before EXEC_PLAN_REVIEW approval.