milestone 13: restructure docs to diataxis, tutorial, every command executed

src/docs_drift_test.zig

@@ -1,5 +1,6 @@
 //! Textual-containment guards that keep the hand-written docs honest
-//! (milestone-11 ruling 3). They assert presence, not correctness — the same
+//! (milestone-11 ruling 3, repointed at the Diátaxis reference pages by
+//! milestone-13 ruling 7). They assert presence, not correctness — the same
 //! contract as openapi.zig's route guard.
 
 const std = @import("std");
@@ -7,7 +8,7 @@ const docs = @import("docs_files");
 const routes = @import("web/routes.zig");
 const model = @import("config/model.zig");
 
-test "every served operation has its own table row in docs/api.md" {
+test "every served operation has its own table row in docs/reference/api.md" {
     const gpa = std.testing.allocator;
     for (routes.table) |route| {
         // Matches one full method + path cell pair ("| GET | `/api/groups` |"),
@@ -17,14 +18,14 @@ test "every served operation has its own table row in docs/api.md" {
             @tagName(route.method), route.pattern,
         });
         defer gpa.free(needle);
-        if (std.mem.indexOf(u8, docs.api_md, needle) == null) {
-            std.debug.print("operation row missing from docs/api.md: {s}\n", .{needle});
+        if (std.mem.indexOf(u8, docs.reference_api_md, needle) == null) {
+            std.debug.print("operation row missing from docs/reference/api.md: {s}\n", .{needle});
             return error.OperationMissingFromApiDoc;
         }
     }
 }
 
-test "every settings key appears in docs/config-reference.md" {
+test "every settings key appears in docs/reference/configuration.md" {
     const gpa = std.testing.allocator;
     var pairs: std.ArrayList(model.SettingPair) = .empty;
     defer {
@@ -33,25 +34,30 @@ test "every settings key appears in docs/config-reference.md" {
     }
     try model.toSettings(.{}, gpa, &pairs);
     for (pairs.items) |pair| {
-        if (std.mem.indexOf(u8, docs.config_reference_md, pair.key) == null) {
-            std.debug.print("settings key missing from docs/config-reference.md: {s}\n", .{pair.key});
+        // Matches the key's own leading table cell ("| `dns.port` |"), not a
+        // bare mention: prose and the annotated example both name most keys, so
+        // a substring search would stay green after a field's row is deleted.
+        const needle = try std.fmt.allocPrint(gpa, "| `{s}` |", .{pair.key});
+        defer gpa.free(needle);
+        if (std.mem.indexOf(u8, docs.reference_configuration_md, needle) == null) {
+            std.debug.print("settings key row missing from docs/reference/configuration.md: {s}\n", .{needle});
             return error.SettingsKeyMissingFromConfigDoc;
         }
     }
 }
 
-test "every cli subcommand has its own reference heading in docs/operator.md" {
+test "every cli subcommand has its own reference heading in docs/reference/cli.md" {
     const gpa = std.testing.allocator;
     const subcommands = [_][]const u8{ "run", "check", "export", "import", "version", "help" };
     for (subcommands) |name| {
-        // Anchors on the reference-section heading ("### `import FILE`" starts
-        // with "### `import"), so prose mentions elsewhere cannot mask a
-        // removed command section.
-        const needle = try std.fmt.allocPrint(gpa, "### `{s}", .{name});
+        // Anchors on the reference-section heading ("## `import FILE`" starts
+        // with "## `import"), so prose mentions elsewhere cannot mask a removed
+        // command section.
+        const needle = try std.fmt.allocPrint(gpa, "## `{s}", .{name});
         defer gpa.free(needle);
-        if (std.mem.indexOf(u8, docs.operator_md, needle) == null) {
-            std.debug.print("subcommand heading missing from docs/operator.md: {s}\n", .{needle});
-            return error.SubcommandMissingFromOperatorDoc;
+        if (std.mem.indexOf(u8, docs.reference_cli_md, needle) == null) {
+            std.debug.print("subcommand heading missing from docs/reference/cli.md: {s}\n", .{needle});
+            return error.SubcommandMissingFromCliDoc;
         }
     }
 }