Groups hexdocs pages by kind and adds a manifest

.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.

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

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

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

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

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"]
     ]