[codex] Package Topic Scout as reusable tool with examples

[ginaecho]

What changed

• packaged the repository as a reusable Topic Scout tool instead of keeping one active topic workspace at the repo root
• added executable LLM-backed scout scoring and research-gap generation
• preserved the current AI-in-hiring run under examples/ai-in-hiring-processes/
• documented the generic workflow, outputs, and Claw/swarm task-manifest support
• improved README wording for discoverability and agent recognition

Why

• the repo should work as a reusable tool for anyone starting a new topic scout
• generated results from one topic should live as tracked examples, not as the default live workspace
• Claw and swarm users need concrete manifests and example outputs in-repo

Impact

• users can initialize a fresh topic workspace at the repo root with make init
• make scout, make opportunities, and make dashboard now support a more complete end-to-end workflow
• example artifacts show what a full run looks like, including claw, swarm, and sequential task manifests
• the repository is easier for AI agents and developers to find and classify correctly

Validation

• python3 -m unittest -q tests.test_core
• make reset
• python3 scripts/orchestrate.py emit --mode claw
• python3 scripts/orchestrate.py emit --mode swarm
• regenerated example dashboard and opportunities artifacts from the example topic workspace

[chatgpt-codex-connector]

💡 Codex Review

topic-scout/scripts/costs.py

Line 28 in dab3625

token_count = int(input_tokens) + int(output_tokens) + int(reasoning_tokens)

Avoid adding reasoning tokens twice

For Responses API usage, output_tokens already includes the reasoning-token component; the official reasoning docs show total usage as input plus output while reasoning_tokens is nested under output details. Any API scout run with reasoning tokens will therefore overstate token_count in reports and dashboards, e.g. 75 input + 1186 output + 1024 reasoning would be recorded as 2285 instead of the API total 1261. Keep reasoning_tokens as a breakdown field but compute totals from total_tokens or input plus output.

---

topic-scout/scripts/scout.py

Line 89 in dab3625

return 0

Preserve auto-accept on OpenAlex-only scouts

When topic.json sets scout_provider to openalex and approval_required is false, this early return exits before the shared auto-accept block below. The same zero-token run via --offline still accepts candidates above the threshold, so legacy OpenAlex-only workspaces stop ingesting any papers and only append empty scout runs. Let this path fall through to the common acceptance logic after recording the zero cost.

ℹ️ About Codex in GitHub

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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".