[MakerFlyFly]

Summary

• Add magpie-discourse topic search <query> [--limit N] so callers can discover relevant forum discussions and open them with topic view. The forum receives the original query, including native filters and ordering.
• Return distinct topics in first-hit order with excerpts and direct post links. Discourse usually selects a representative post for each topic. matches contains the distinct posts returned on the pages read, so its length cannot establish a total hit or contribution count.
• Report a proven extra topic with truncated and Discourse's ten-page window with the independent server_limit_reached flag. Valid empty searches succeed. An explicit null group on page 1 gives a keyword hint, while a null later page identifies the failed page. Read failures produce no partial JSON.

Type of change

• Tool / bridge
• Python package
• Documentation

Test plan

Current head bc5dd1bce83c298381515d019f2c0704e772dc68 is one commit on b6ccd434a54bdd4761fb487d7b55aaa8bd89dbc0. Its complete Git tree and canonical patch are identical to the prior publication 89d47d81d9edbe4f4adb28abb4eeaf71e639ee9a.

• On the new SHA, all 43 non-pytest hooks pass, including the workspace static checks. Committed-diff pytest selects Discourse and passes all 410 tests, including 40 search cases. The optional native Claude check skips internally because its CLI is absent.
• Magpie pre-first-PR A–E passes over the complete one-commit diff, with 0 blocking and 0 advisory items. The parent is the publication base and the new commit reconstructs the same nine-file, +534/−11 change.
• Same-tree verification previously run on 89d47d81 includes 410 package tests on each of Linux/Python 3.12 and Windows/Python 3.14, ruff, format, mypy and five integration suites (vendor-neutrality-score, skill-and-tool-validator, dev, spec-validator and spec-inventory). These results retain their original SHA.
• Apache RAT 0.18 passed locally on the same tree using the workflow's pinned SHA-512 and scan arguments, with no unapproved licences.
• Historical anonymous validation on audited 86811931 exercised a filter-only query and a normal two-topic search in two GETs. Publication README rendering and links were checked on the identical 89d47d81 file content. Owner audit

RFC-AI-0004 compliance

• Sandbox — use the existing configured HTTPS origin and forum-path checks, including on redirects.
• Vendor neutrality — retain partial coverage of the mail-archive contract and keep Discourse behavior in its adapter.
• Write-access discipline — search uses GET, and automated HTTP tests use simulated transport.
• Privacy LLM — return forum data to the caller, which establishes visibility and approval before model use.

Linked issues

Refs #307, following merged #1755 and #1841. Owner audit is recorded in fork PR #34 and fork issue #33.

Notes for reviewers

• The default limit is 100 distinct topics. A further distinct topic proves count truncation. Search reads at most ten result pages, with a configurable page size, and redirects can add HTTP requests. Changes in ranking between pages can skip hits even when duplicates are removed.
• The separate command-wide budget design called for in feat(tools/discourse): list category topics by latest activity #1841 predates search and remains under review on the contributor fork. Budget design · Budget candidate
• The PR contains one commit and nine files, +534/−11. It provides the search slice while the remaining feat(tools/discourse): forum bridge for projects that use Discourse instead of mailing lists #307 capabilities stay open.

AI disclosure

AI-generated PR description. OpenAI Codex CLI 0.166.0-alpha.5.1 (GPT-6) assisted with implementation, tests, review follow-up and publication.
The author has manually reviewed the complete change through audited 868119319e05a0e213b613af76d4ca8e0c1eaa24 and takes responsibility for this contribution. The published change is equivalent to the reviewed changes, with the existing publication tree preserved through the squash.