From cc14c64ea21fe2d68dbadedd9e3b7164fb6fa084 Mon Sep 17 00:00:00 2001 From: JohnnyT Date: Mon, 5 Oct 2026 05:16:41 -0600 Subject: [PATCH] Groups hexdocs pages by kind and adds a manifest The hexdocs sidebar groups the shipped pages under "How-to guides" (docs/guides/) and "Explanation" (docs/explanation/) where one "Guides" group held them all. The README and the CHANGELOG stay ungrouped at the top, main stays the README, and the API reference and package files do not change. Two how-to pages take "How to" titles: the two-vaults page and the scope-in-jobs page. Their files keep their names, and the link text in README.md and docs/README.md follows the new titles. Adds .claude/diataxis.md, the docs manifest the documentation tools read: where each kind of page lives, the audience, and that examples here are domain-free. Refs: ece-2fk9 --- .claude/diataxis.md | 42 +++++++++++++++++++ README.md | 4 +- docs/README.md | 4 +- docs/guides/scope-in-jobs-and-projectors.md | 2 +- .../two-vaults-customer-and-agreement.md | 2 +- mix.exs | 3 +- 6 files changed, 50 insertions(+), 7 deletions(-) create mode 100644 .claude/diataxis.md diff --git a/.claude/diataxis.md b/.claude/diataxis.md new file mode 100644 index 0000000..cd7bc51 --- /dev/null +++ b/.claude/diataxis.md @@ -0,0 +1,42 @@ +--- +# The docs manifest the documentation tools read. Generated from the family's manifest +# table: change a key there and regenerate. The two prose lines below may be sharpened. +product: encryptor_ecto +family: foundation +audience: Elixir developers with Ecto schemas whose columns must be encrypted at rest +tone: "plain, second person, no marketing" +terminology: + use: + - execution + - chart + - document + - revision + avoid: + - "run (noun)" + - workflow instance +example_world: none +docs_root: docs +quadrants: + tutorials: docs/tutorials + how_to: docs/guides + reference: docs/reference + explanation: docs/explanation +readme: README.md +reference_generator: ex_doc +publish: hexdocs +contributor_paths: + - docs/adr + - docs/plans + - docs/spikes + - docs/research + - docs/design + - docs/measurements + - CLAUDE.md +executed_snippets: + - test/encryptor/ecto/scope_in_jobs_guide_test.exs + - test/encryptor/ecto/two_vaults_guide_test.exs +readme_max_lines: 250 +--- + +Ecto types and a migrator over encryptor: encrypted columns and blind indexes. +Examples are domain-free: a foundation package teaches no domain. diff --git a/README.md b/README.md index 94de89d..3e2fa01 100644 --- a/README.md +++ b/README.md @@ -398,12 +398,12 @@ path. The index is not an extra and links at its GitHub path: `"gcp_kms_ciphertext"` row, and the shred: destroying the key version, deleting the row, the restore window, and what the application sees in between. -- [Two vaults: a customer scope and an agreement scope](docs/guides/two-vaults-customer-and-agreement.md) - +- [How to keep a customer scope and an agreement scope in two vaults](docs/guides/two-vaults-customer-and-agreement.md) - a customer vault for platform data and credentials beside an agreement vault for data shared under a data agreement: the two key tables, the process resolver and a resolver fed from the row, and the shred of one agreement, with what each vault's shred reaches. -- [Resolving the scope in jobs and projectors](docs/guides/scope-in-jobs-and-projectors.md) - +- [How to resolve the scope in jobs and projectors](docs/guides/scope-in-jobs-and-projectors.md) - why the scope stops at the process, carrying it into a `Task` with `Encryptor.Ecto.Scope.wrap/2`, into a background job through its arguments, and into an event projector through a resolver the projector diff --git a/docs/README.md b/docs/README.md index ac8b2c4..17dc644 100644 --- a/docs/README.md +++ b/docs/README.md @@ -38,13 +38,13 @@ Task-shaped, for someone who already understands the target state. shred - destroying the key version, deleting the row, the restore window, and the answers the application sees at each step, including the one ADR-0005 Amendment A5 proposes. -- [Two vaults: a customer scope and an agreement scope](guides/two-vaults-customer-and-agreement.md) - +- [How to keep a customer scope and an agreement scope in two vaults](guides/two-vaults-customer-and-agreement.md) - a customer vault for platform data and credentials beside an agreement vault for data shared under a data agreement: why two vaults rather than a composite selector, the two key tables, the process resolver and a resolver fed from the row, the shred of one agreement, and what each vault's shred reaches. -- [Resolving the scope in jobs and projectors](guides/scope-in-jobs-and-projectors.md) - +- [How to resolve the scope in jobs and projectors](guides/scope-in-jobs-and-projectors.md) - why the scope stops at the process that set it, capturing it in the caller and re-establishing it with `wrap/2` in a `Task` and in a background job's `perform/1` (the Oban worker as one line of delegation), and a projector diff --git a/docs/guides/scope-in-jobs-and-projectors.md b/docs/guides/scope-in-jobs-and-projectors.md index 2828eb5..a527ded 100644 --- a/docs/guides/scope-in-jobs-and-projectors.md +++ b/docs/guides/scope-in-jobs-and-projectors.md @@ -1,4 +1,4 @@ -# Resolving the scope in jobs and projectors +# How to resolve the scope in jobs and projectors This guide is for a host whose encrypted writes and reads do not all happen in the request that knows the scope. A request fans work out to a `Task`, a diff --git a/docs/guides/two-vaults-customer-and-agreement.md b/docs/guides/two-vaults-customer-and-agreement.md index 26f7260..c248305 100644 --- a/docs/guides/two-vaults-customer-and-agreement.md +++ b/docs/guides/two-vaults-customer-and-agreement.md @@ -1,4 +1,4 @@ -# Two vaults: a customer scope and an agreement scope +# How to keep a customer scope and an agreement scope in two vaults This guide is for a SaaS host that holds two kinds of data with two different lifetimes. Its own platform data - a customer's account, the diff --git a/mix.exs b/mix.exs index c5368bb..7a0f6f3 100644 --- a/mix.exs +++ b/mix.exs @@ -61,7 +61,8 @@ defmodule Encryptor.Ecto.MixProject do "docs/guides/scope-in-jobs-and-projectors.md" ], groups_for_extras: [ - Guides: ~r{docs/} + "How-to guides": ~r{docs/guides/}, + Explanation: ~r{docs/explanation/} ], skip_undefined_reference_warnings_on: ["CHANGELOG.md"] ]