Split the row-level security page and fix its example #715

Parent

#698

What to build

The 736-line RLS page mixes explanation, how-to and reference, shows its first example at line 111, and never shows what a scoped query returns; its example's policy reads a membership table it never declares, so on Postgres the models as shown should fail to migrate.

It splits into an explanation (concepts/row-level-security.md: what RLS is and how Ferro's session settings drive it), a how-to (the existing guide page: set up and use it, with a scoped query beside an unscoped one) and a reference (reference/row-level-security.md: RowSecurity, RowPolicy, the command matrix, the shorthand cast). The example declares every table its policies read and runs on Postgres in the harness (skipped without Postgres, as the other Postgres examples are). Before writing about round trips and which open transactions see a new set_config value, the ticket confirms the behaviour in the code and states it once; the session docstrings ticket (#720) aligns its docstrings to it.

Pages: guide/row-level-security.md, concepts/row-level-security.md, reference/row-level-security.md

Acceptance criteria

• Every fact on the page matches the code at the time of the PR; each High finding in the audit rows below is fixed, and each Medium/Low finding is fixed or answered in the PR body with the reason it was left.
• Each page is one kind (tutorial, how-to, reference or explanation) and opens with one sentence saying what it covers, then an example on the first screen (writing-for-humans rules 1–2).
• Each page uses one running example, declared once near the top and reused; each section shows only what changed (rule 3).
• Every code block has a lead-in sentence ending in a colon and a result sentence after it, and shows its result: printed output, or the asserted value inside the embedded snippet range (rules 7–8). Snippet end: markers sit below the assert or print that holds the result.
• Every copyable block either shows the async with engines.session(): wrapper or sits under a sentence that says it runs inside one and links to Connections › Sessions; the page's first block shows the wrapper.
• Every inline Python block that does real work runs under the harness ({test=run prelude=<name>}) or moves into an example script; a block left compile-only says why in its fence marker.
• Every lambda passed to a query method names its parameter after the model in lowercase singular (AGENTS.md I-8); python -m tests._docs_checks reports no violation for the owned files.
• Every error check in an owned example fails when the expected error is not raised (try/except/else: raise AssertionError, or the harness helper).
• Field-declaring examples show both declaration styles as tabs, each backed by a runnable script (AGENTS.md I-7), and the twins use the one Annotated idiom recorded in the docs conventions.
• Headings are short sentence-case noun phrases naming the feature (rule 5); how-to titles name the goal (rule 24); no minimising words (rule 17); admonitions follow rule 20.
• No ADR numbers, issue numbers, codenames, dated or release-bound notes, or contributor-only references in page text; version markers are self-contained blocks at the end of a section.
• Reference material that has a home in Reference is linked, not repeated; each topic ends with a pointer to its reference entry (rule 4).

Files owned

• Create: docs/pages/concepts/row-level-security.md, docs/pages/reference/row-level-security.md
• Modify: docs/pages/guide/row-level-security.md, docs/examples/row_level_security.py, docs/examples/row_level_security_annotated.py

Interfaces

• Consumes: docs conventions (AGENTS.md ticket (AGENTS.md: rewrite I-8 for the lambda-only query API, add a docstring invariant, record the docs conventions #703))
• Consumes: harness (harness ticket (Docs harness: run inline blocks with a prelude, run docstring examples, and check lambda names and error checks #704))
• Produces: Section anchor #session-settings on the RLS concepts page: the one statement of set_config round trips and visibility, linked by the session docstrings ticket (Docstrings: connect, fields, checks, row security, raw SQL, sessions, settings and exceptions #720).
• Produces: New pages wired into the nav by the nav ticket (Navigation: six tabs, sentence-case labels that match page titles, moved pages redirected #723).

Test scenarios

• Happy path: the strict site build succeeds and every snippet range on the owned pages renders without leading indentation.
• Happy path: every owned example script runs to completion under tests/test_docs_examples.py, and every inline block marked {test=run ...} runs.
• Error path: deleting the raise an owned example's error check expects makes that example's test fail.
• Edge case: python -m tests._docs_checks over the owned files exits 0; renaming one lambda parameter to t makes it exit 1 naming the file and line.
• Integration (Postgres): the RLS example migrates and a scoped query returns only the current tenant's rows while the unscoped one returns all.

Verify

uv run --no-sync zensical build --clean --strict
uv run --no-sync pytest tests/test_docs_examples.py -q --no-cov -p no:cacheprovider -n 8
uv run --no-sync python -m tests._docs_checks docs/pages/guide/row-level-security.md docs/pages/concepts/row-level-security.md docs/examples/row_level_security.py docs/examples/row_level_security_annotated.py

Blocked by

• Docs site config: Zensical features, Markdown extensions, API reference options and a strict build #701, AGENTS.md: rewrite I-8 for the lambda-only query API, add a docstring invariant, record the docs conventions #703, Docs harness: run inline blocks with a prelude, run docstring examples, and check lambda names and error checks #704

Audit findings