Give agents a docs tool that searches the user docs#1925

Summary by CodeRabbit

• New Features
  • Added searchable Ployz documentation, with relevant results and excerpts.
  • Documentation can be consulted through a read-only tool in local and cloud workflows. You can search by topic or open a page directly, including to a specific section. If a page can’t be found, the tool suggests a matching page and lists available pages.
• Documentation
  • Updated project and environment field descriptions to identify them as names without specifying what happens when they’re omitted.

This PR adds embedded documentation search and page lookup to ployz-store, exposes them through a read-only agent tool, and updates build, artifact-key, and CI handling for user documentation.

Changes: Documentation search and agent access

Layer / File(s)	Summary
Documentation assets and build inputs core/crates/ployz-store/build.rs, Dockerfile, core/scripts/artifacts.py, core/scripts/test_artifacts.py, scripts/ci.py, scripts/test-ci.py	The build collects titled Markdown pages from docs/user and generates embedded assets. The SDK copies the documentation, artifact keys include embedded documentation inputs, and CI selects Rust checks when user documentation changes.
Documentation parsing and search core/crates/ployz-store/src/docs/split.rs, core/crates/ployz-store/src/docs/index.rs, core/crates/ployz-store/Cargo.toml	The code parses Markdown pages into sections and indexes them with weighted fields, stemming, synonyms, and fuzzy matching.
Page lookup and search results core/crates/ployz-store/src/docs.rs, core/crates/ployz-store/src/lib.rs	The public docs module provides search results, page content, page paths, and missing-page suggestions. Search results include excerpts.
Agent tool and catalog integration core/crates/ployz-store/src/tools/docs.rs, core/crates/ployz-store/src/tools/mod.rs, core/crates/ployz-store/src/tools/*.rs, core/crates/ployz-store/tests/agent_tool_calls.rs, core/crates/ployz-store/tests/snapshots/*, core/crates/ployz-sdk/tests/node_agent_sweep.js	The tool catalog adds the read-only docs tool and instructs the agent to consult documentation for Ployz questions. Tests and snapshots cover search and page queries. Project and environment field descriptions no longer say that omission selects the current scope; field types and runtime behavior remain unchanged.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature · Unblocks: 1 PR

Sequence Diagram(s)

mermaid

1	sequenceDiagram
2	participant Agent
3	participant DocsTool
4	participant docs_lookup
5	participant Index
6	participant EmbeddedPages
7	Agent->>DocsTool: Submit documentation query
8	DocsTool->>docs_lookup: Call lookup(query)
9	docs_lookup->>Index: Search a non-path query
10	Index-->>docs_lookup: Return ranked sections
11	docs_lookup->>EmbeddedPages: Resolve a documentation path
12	EmbeddedPages-->>docs_lookup: Return page content or path match
13	docs_lookup-->>DocsTool: Return results, page, or missing-page suggestion
14	DocsTool-->>Agent: Return documentation response

Documentation edits can cause the artifact-key validation test to fail until the clean-tree guard includes the embedded docs path.

The new capability reads bundled documentation and adds no customer-data access or write authority. The main remaining risk is resource containment: search runs synchronously, and its input-processing cost is not locally bounded.

Retained concerns

• Low · security · inferred: The new search performs input-sized normalization and fuzzy-query construction synchronously inside its caller, including the dashboard’s native SDK call, without a docs-level query-length or term-count budget. This creates a possible shared-process availability hazard. Hosted queries are model-mediated behind caller and thread checks, and the loop is capped at 25 iterations; practical exhaustion and cross-tenant impact remain unverified.

Security review details

Security Blast Radius

• inferred — The lookup’s data exposure is the embedded documentation corpus, not organization records, secrets, or arbitrary host files. Resource impact belongs to the process executing lookup: the local MCP process or the dashboard process loading the native SDK. Production process sharing across organizations was not established.

Security Findings and Attack Paths

• inferred — A member-controlled message can influence model-generated docs arguments, which reach synchronous search. Numerous unknown terms can increase fuzzy-query work. The result-count cap, long-token filter, caller/thread checks, and 25-step loop limit reduce exposure but do not bound each search. This is an inferred availability concern, not a demonstrated denial-of-service attack.

Trust Boundaries and Controls

• observed — The hosted handler retains caller resolution and thread-ownership checks, and constructs tool context from that caller’s organization. The new docs plan ignores this context because its data is static; it does not use documentation lookup to acquire tenant-specific authority.
• observed — Read-only describes the docs plan, not every enclosing MCP operation. MCP still performs configured credential resolution, organization selection, or a local Store sweep before dispatch. Those setup paths predate this PR and do not receive the docs query as a credential, destination, or Store selector.

Resilience and Maintainability Implications

• inferred — Atomic publication prevents a failed initialization from exposing a partial index or another caller’s query-specific state. However, the synchronous SDK call cannot be preempted by an ordinary JavaScript abort signal while native search is executing; the actual production CPU and panic-containment boundary remains unverified.

Hardening Proposals

• proposed — Apply a query-byte and analyzed-term budget before search, with a structured refusal when exceeded. Validate worst-case fuzzy-query cost under the hosted execution model; use an interruptible worker boundary if acceptable latency cannot be guaranteed within those budgets.

^Failed Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage	Warning	Docstring coverage is 68.63% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 51 functions across 20 files. (1 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

^Passed Passed checks: 4 passed

Check name	Status	Explanation
Title check	Passed	The title clearly and concisely describes the main change: adding a documentation search tool for agents.
Description check	Passed	The description directly explains the docs tool, embedded documentation search, build changes, testing, and integration impact.
Linked Issues check	Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 68.63% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 51 functions across 20 files. (1 skipped: 1 unsupported.)

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.