From fbf230b414679ab044d87e3dfbdf12fae62c62ed Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Fri, 20 Feb 2026 09:53:07 -0800 Subject: [PATCH] Move Mikado cards to topic subdirectory, not plans/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mikado cards are discovered through failed attempts, not designed upfront — they don't belong in plans/. Cards now live where they topically belong (how-to/authentik/ for this chain). Updated agent-change-process to document this convention. Co-Authored-By: Claude Opus 4.6 --- docs/how-to/agent-change-process.md | 3 ++- .../build-authentik-container.md | 1 - .../create-authentik-secrets.md | 1 - .../how-to/{plans => authentik}/deploy-authentik.md | 1 - .../provision-authentik-database.md | 1 - docs/how-to/how-to.md | 13 +++++++++---- docs/how-to/plans/plans.md | 5 +---- 7 files changed, 12 insertions(+), 13 deletions(-) rename docs/how-to/{plans => authentik}/build-authentik-container.md (99%) rename docs/how-to/{plans => authentik}/create-authentik-secrets.md (99%) rename docs/how-to/{plans => authentik}/deploy-authentik.md (99%) rename docs/how-to/{plans => authentik}/provision-authentik-database.md (99%) diff --git a/docs/how-to/agent-change-process.md b/docs/how-to/agent-change-process.md index 7e862c7..7c3bfa7 100644 --- a/docs/how-to/agent-change-process.md +++ b/docs/how-to/agent-change-process.md @@ -93,7 +93,8 @@ tags: ### Writing Cards -- Cards live in `docs/how-to/` — they're how-to docs with lifecycle metadata +- **Mikado cards are not plans.** Plans are designed upfront; Mikado cards are discovered through failed attempts. Don't put Mikado prerequisite cards in `docs/how-to/plans/`. +- Cards live in a topic subdirectory under `docs/how-to/` (e.g., `docs/how-to/authentik/` for the deploy-authentik chain). The goal card may live in `plans/` if it started as a plan. - Keep cards brief (<30 seconds to read) - Link to other cards rather than inlining their content - Document what was learned from failures, not just what to do diff --git a/docs/how-to/plans/build-authentik-container.md b/docs/how-to/authentik/build-authentik-container.md similarity index 99% rename from docs/how-to/plans/build-authentik-container.md rename to docs/how-to/authentik/build-authentik-container.md index e1326f3..71365d7 100644 --- a/docs/how-to/plans/build-authentik-container.md +++ b/docs/how-to/authentik/build-authentik-container.md @@ -4,7 +4,6 @@ status: active modified: 2026-02-20 tags: - how-to - - plans - authentik --- diff --git a/docs/how-to/plans/create-authentik-secrets.md b/docs/how-to/authentik/create-authentik-secrets.md similarity index 99% rename from docs/how-to/plans/create-authentik-secrets.md rename to docs/how-to/authentik/create-authentik-secrets.md index 7cf57a4..351805a 100644 --- a/docs/how-to/plans/create-authentik-secrets.md +++ b/docs/how-to/authentik/create-authentik-secrets.md @@ -4,7 +4,6 @@ status: active modified: 2026-02-20 tags: - how-to - - plans - authentik - secrets --- diff --git a/docs/how-to/plans/deploy-authentik.md b/docs/how-to/authentik/deploy-authentik.md similarity index 99% rename from docs/how-to/plans/deploy-authentik.md rename to docs/how-to/authentik/deploy-authentik.md index 338e15f..6c59291 100644 --- a/docs/how-to/plans/deploy-authentik.md +++ b/docs/how-to/authentik/deploy-authentik.md @@ -8,7 +8,6 @@ requires: - create-authentik-secrets tags: - how-to - - plans - authentik - security - oidc diff --git a/docs/how-to/plans/provision-authentik-database.md b/docs/how-to/authentik/provision-authentik-database.md similarity index 99% rename from docs/how-to/plans/provision-authentik-database.md rename to docs/how-to/authentik/provision-authentik-database.md index 49381f2..e99f76b 100644 --- a/docs/how-to/plans/provision-authentik-database.md +++ b/docs/how-to/authentik/provision-authentik-database.md @@ -4,7 +4,6 @@ status: active modified: 2026-02-20 tags: - how-to - - plans - authentik - postgresql --- diff --git a/docs/how-to/how-to.md b/docs/how-to/how-to.md index edd5b2f..e4b625e 100644 --- a/docs/how-to/how-to.md +++ b/docs/how-to/how-to.md @@ -63,8 +63,13 @@ Migration and transition plans for upcoming infrastructure changes. | [[harden-zot-registry]] | Add authentication and tag immutability to zot registry | | [[forgejo-actions-dashboard]] | Grafana dashboard for Forgejo Actions CI metrics | | [[upgrade-grafana-helm-chart]] | Upgrade Grafana Helm chart from 8.8.2 to 11.x | -| [[deploy-authentik]] | Deploy Authentik identity provider to replace Dex | -| [[build-authentik-container]] | Build Nix container image for Authentik | -| [[provision-authentik-database]] | Create PostgreSQL database for Authentik | -| [[create-authentik-secrets]] | Create 1Password secrets for Authentik | | [[operationalize-reolink-camera]] | Cloud-free NVR with Frigate and ring buffer recording | + +## Authentik + +Mikado chain for replacing Dex with Authentik. Track progress with `mise run docs-mikado deploy-authentik`. + +- [[deploy-authentik]] +- [[build-authentik-container]] +- [[provision-authentik-database]] +- [[create-authentik-secrets]] diff --git a/docs/how-to/plans/plans.md b/docs/how-to/plans/plans.md index a4c3293..c53cfdc 100644 --- a/docs/how-to/plans/plans.md +++ b/docs/how-to/plans/plans.md @@ -21,8 +21,5 @@ Plans differ from regular how-to guides in that they describe work that has been | [[harden-zot-registry]] | Planned | Add authentication and tag immutability to zot registry | | [[forgejo-actions-dashboard]] | Planned | Grafana dashboard and custom Prometheus exporter for Forgejo Actions CI metrics | | [[upgrade-grafana-helm-chart]] | Planned | Upgrade Grafana Helm chart from 8.8.2 to 11.x (3 phases) | -| [[deploy-authentik]] | Active (C2) | Deploy Authentik identity provider to replace Dex for full SSO and user management | -| [[build-authentik-container]] | Active (C2) | Build Nix container image for Authentik (prerequisite of deploy-authentik) | -| [[provision-authentik-database]] | Active (C2) | Create PostgreSQL database for Authentik (prerequisite of deploy-authentik) | -| [[create-authentik-secrets]] | Active (C2) | Create 1Password secrets for Authentik (prerequisite of deploy-authentik) | +| [[deploy-authentik]] | Active (C2) | Deploy Authentik IdP — Mikado chain tracked in `how-to/authentik/` | | [[operationalize-reolink-camera]] | Planned | Cloud-free NVR with Frigate, object detection, and ring buffer recording to sifaka |