[richwrd]

The project has two canonical sources — docs/PGFATHOM.md and the specs under openspec/ — but both are the maintainer's design record, written in Portuguese, and neither was written to orient someone who's read neither. The README covers the end user well; there was no equivalent for someone arriving to understand the code before touching it.

docs/guide/ is that layer: seven numbered sections (overview, architecture, features & safety, usage, positioning & metrics, contributing), each with a README.md index — the GitHub convention that auto-renders when browsing into a folder. In English, following the rule already written in CONTRIBUTING.md for anything contributor-facing.

No page fully duplicates canonical content — each one orients and links back to the corresponding section of docs/PGFATHOM.md, the README, or the specs, so the two sources never silently drift apart. All relative links were validated by script.

README.md gets one line in the Contributing section pointing to the guide.

What changes, and why

How it was verified

• make fmt && make lint && make test
• make test-integration (if it touches SQL, the catalog, or validation)

Checks

• Nothing writes to the target database
• No row value can reach output, logs or errors
• New behaviour has a change under openspec/, validating with --strict
• A new dependency, if any, is justified with measured numbers

[Copilot]

Pull request overview

Adds a newcomer-oriented, English-language documentation guide under docs/guide/ that provides a navigable hierarchy and pointers back to the project’s canonical design/spec sources, and links it from the root README so contributors can find it quickly.

Changes:

• Add docs/guide/ with section indexes and supporting pages covering overview, architecture, features/safety, usage, positioning/metrics, and contributing.
• Cross-link guide pages back to docs/PGFATHOM.md, openspec/specs/, and relevant README.md sections to avoid duplicating canonical content.
• Update README.md to point new contributors to the guide.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Adds a Contributing-section pointer to the new docs/guide/ entry point.
docs/guide/README.md	Introduces the guide’s purpose and table of contents.
docs/guide/01-overview/README.md	Overview section index and reading order.
docs/guide/01-overview/the-problem.md	Explains the motivating problem the tool addresses.
docs/guide/01-overview/what-it-does.md	Summarizes what pgfathom does and its outputs/verdicts.
docs/guide/02-architecture/README.md	Architecture section index for layers/model/algorithm.
docs/guide/02-architecture/layers.md	Documents the layer boundaries and tech stack.
docs/guide/02-architecture/data-model.md	Sketches the core internal model structs and concepts.
docs/guide/02-architecture/algorithm.md	Describes the 7-stage discovery pipeline at a high level.
docs/guide/03-features-and-safety/README.md	Features & safety section index.
docs/guide/03-features-and-safety/naming-profiles.md	Explains naming profiles and normalization design.
docs/guide/03-features-and-safety/safety-guarantees.md	Documents the non-negotiable safety guarantees and enforcement.
docs/guide/03-features-and-safety/known-pitfalls.md	Lists concrete failure modes/pitfalls and how they’re handled.
docs/guide/04-usage/README.md	Usage section index.
docs/guide/04-usage/cli-reference.md	Adds an install/flags/output reference page.
docs/guide/05-positioning-and-metrics/README.md	Positioning & metrics section index.
docs/guide/05-positioning-and-metrics/prior-art.md	Provides a map of the “prior art” argument with links to README.
docs/guide/05-positioning-and-metrics/measuring-correctness.md	Explains the benchmark metric framing and links to full numbers.
docs/guide/06-contributing/README.md	Provides a shortest-path contributor entry and PR evaluation rules.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.