docs: bilingual technical documentation

[DataDave-Dev]

Adds a documentation/ folder with technical docs in English and Spanish (language switcher on each page):

• architecture.md — how becwright works, with a flow diagram.
• usage.md — install, commands, and the .bec/rules.yaml schema.
• writing-checks.md — the check contract, forbid, and custom checks.
• portability.md — export/import, the bundle format, and the catalog.

Linked from README.md and README.es.md.

Summary by CodeRabbit

• Documentation
  • Added a new documentation section to the main README in English and Spanish.
  • Added English and Spanish documentation landing pages with links to core topics.
  • Published detailed guides on architecture, usage, writing checks, and portability.
  • Expanded end-user instructions for setup, commands, exit codes, rule file structure, custom checks, and importing ready-made rules.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a complete documentation set for becwright in English and Spanish. New files cover architecture and check flow, CLI usage and rules schema, writing custom checks, and BEC bundle portability. Root READMEs gain a Documentation section linking to the new documentation/ directory.

Changes

Documentation site

Layer / File(s)	Summary
README links and index pages README.md, README.es.md, documentation/README.md, documentation/README.es.md	Adds a Documentation section to both root READMEs and creates bilingual landing pages in documentation/ linking to all doc topics.
Architecture documentation/architecture.md, documentation/architecture.es.md	Describes core modules (cli.py, rules.py, engine.py, git.py, checks/, bundle.py), the pre-commit check flow with a Mermaid diagram, the stdin/stdout/exit-code check contract, and determinism explanation.
Usage documentation/usage.md, documentation/usage.es.md	Covers installation, becwright install hook setup, CLI command table, exit codes, rules.yaml schema with field descriptions and a full example, glob syntax, and catalog import.
Writing checks documentation/writing-checks.md, documentation/writing-checks.es.md	Documents the check contract, built-in forbid check flags and table of built-ins, a Node.js custom check example with YAML wiring, and a self-reference caveat with paths scoping guidance.
Portability documentation/portability.md, documentation/portability.es.md	Documents becwright export/import CLI, confirmation and overwrite-refusal behavior, .bec.yaml bundle format fields, three check kinds (builtin, script, command) and their bundle contents, and the becs/ catalog directory.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hopped through the docs with a joyful leap,
Spanish and English, no secrets to keep!
Architecture, usage, checks — all in a row,
Portability bundled with a tidy bow.
Every README now points the right way,
becwright's story is clearer today! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers the change, but it omits the required Why section and the checklist items.	Add the missing Why section and complete the checklist with test status, coverage, atomic commits, and docs notes.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and clearly points to the new bilingual technical documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/technical-documentation

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (2)

documentation/writing-checks.es.md (1)

20-25: 📐 Maintainability & Code Quality | 🔵 Trivial

Muestra el contexto de rules: en ambos ejemplos YAML.

Tal como están, ambos fragmentos no son ejemplos completos de rules.yaml. Sin un wrapper rules: o una nota que diga que son entradas para pegar debajo de rules:, alguien puede copiar YAML inválido.

Also applies to: 57-62

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@documentation/writing-checks.es.md` around lines 20 - 25, The YAML examples
are missing the surrounding rules context, so update the documentation snippets
around the referenced rule entry and the other example to show them under a
rules: wrapper or explicitly label them as content to paste below rules:. Make
sure the examples remain valid and clearly indicate the parent key so readers
can copy them into a correct rules.yaml structure.

documentation/writing-checks.md (1)

20-25: 📐 Maintainability & Code Quality | 🔵 Trivial

Show the enclosing rules: context for both YAML examples.

As written, both snippets are fragments, not standalone rules.yaml examples. Without an explicit rules: wrapper or a note that these are list items to paste under rules:, readers can copy invalid YAML.

Also applies to: 57-62

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@documentation/writing-checks.md` around lines 20 - 25, The YAML examples are
currently shown as bare list fragments, so update the `writing-checks.md`
examples to include the enclosing `rules:` context around both snippets (or
clearly label them as items to paste under `rules:`). Use the existing
`no-debugger-js` rule example and the other YAML example in this section to make
each snippet standalone and valid-looking when copied.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@documentation/writing-checks.es.md`:
- Around line 20-25: The YAML examples are missing the surrounding rules
context, so update the documentation snippets around the referenced rule entry
and the other example to show them under a rules: wrapper or explicitly label
them as content to paste below rules:. Make sure the examples remain valid and
clearly indicate the parent key so readers can copy them into a correct
rules.yaml structure.

In `@documentation/writing-checks.md`:
- Around line 20-25: The YAML examples are currently shown as bare list
fragments, so update the `writing-checks.md` examples to include the enclosing
`rules:` context around both snippets (or clearly label them as items to paste
under `rules:`). Use the existing `no-debugger-js` rule example and the other
YAML example in this section to make each snippet standalone and valid-looking
when copied.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7e44976e-7df6-4155-bbe9-0054ba174e4b

📥 Commits

Reviewing files that changed from the base of the PR and between f9cd43d and 6e7e7d5.

📒 Files selected for processing (12)

• README.es.md
• README.md
• documentation/README.es.md
• documentation/README.md
• documentation/architecture.es.md
• documentation/architecture.md
• documentation/portability.es.md
• documentation/portability.md
• documentation/usage.es.md
• documentation/usage.md
• documentation/writing-checks.es.md
• documentation/writing-checks.md