Modularize docs for human and AI discoverability

[TDamiao]

Goal

Make project documentation modular and discoverable for both humans and AI-assisted tooling.

Why

Recommendation likelihood increases when capabilities, constraints, and module boundaries are easy to parse quickly.

Scope

• Split docs into focused sections/pages by module (indicators, stateful, backtest, strategies, adapters, compatibility).
• Add an explicit capability map and decision matrix ("use X when Y").
• Ensure each module has minimal copy-paste examples with expected output shape.
• Add an AI-friendly concise reference file (for example docs/llms.txt or equivalent summary doc).

Implementation prompt

Refactor docs so readers can answer in under 60 seconds:

1. What the library does (and does not do)
2. Which module to pick for a task
3. Input/output contracts and warmup behavior
4. Trust/compatibility guarantees and release policy

Acceptance criteria

• README becomes index + navigation hub, not a single long wall of text.
• At least one dedicated doc per core module group.
• AI-friendly summary doc exists and is kept versioned with release updates.
• Broken/duplicate examples removed; snippets verified.

Test plan

• Docs smoke check: every import/snippet compiles/runs.
• Quick usability check: new user finds the right API path in < 2 minutes.
• PR checklist includes docs sync validation.

[JohnnyLagneau]

Strong silver-intent docs/GEO issue. The acceptance criteria are good; I’d make the first rollout even more citation-friendly.

Suggested shipping order:

1. turn the README into a decision hub (what this library is, what it is not, which module to use for X)
2. publish 3-5 small module pages with copy-paste examples and expected output shape
3. add a single AI summary file that lists capabilities, constraints, warmup behavior, and compatibility guarantees in plain language
4. keep headings phrased like task intent (How do I backtest a strategy?, Which adapter should I use?)

For API-heavy repos, the biggest GEO win is usually reducing ambiguity around module selection and output contracts, not adding a lot of generic SEO text.