From ccd63ba0665be4adcf9a746a41217b7e4309fde5 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 28 Jan 2026 14:17:13 -0800
Subject: [PATCH] Add org-agenda-api consolidation design plan

Documents the plan to:
- Move container builds from colonelpanic-org-agenda-api to dotfiles
- Consolidate fly.io deployment into dotfiles/org-agenda-api/
- Add cachix substituter for faster builds
- Keep custom-config.el for container-specific glue only

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 ...-28-org-agenda-api-consolidation-design.md | 152 ++++++++++++++++++
 1 file changed, 152 insertions(+)
 create mode 100644 docs/plans/2026-01-28-org-agenda-api-consolidation-design.md

diff --git a/docs/plans/2026-01-28-org-agenda-api-consolidation-design.md b/docs/plans/2026-01-28-org-agenda-api-consolidation-design.md
new file mode 100644
index 00000000..3b7cd022
--- /dev/null
+++ b/docs/plans/2026-01-28-org-agenda-api-consolidation-design.md
@@ -0,0 +1,152 @@
+# Org-Agenda-API Consolidation Design
+
+## Overview
+
+Consolidate org-agenda-api container builds and fly.io deployment into the dotfiles repository. This eliminates the separate `colonelpanic-org-agenda-api` repo and provides:
+
+- Container outputs available to NixOS machines directly
+- Fly.io deployment from the same repo
+- Fewer repos to maintain
+- Cachix integration for faster builds
+
+## Directory Structure
+
+```
+/home/imalison/dotfiles/
+├── nixos/
+│   ├── flake.nix              # Main flake, adds container output
+│   ├── org-agenda-api.nix     # Existing tangling module (stays here)
+│   └── ...
+├── org-agenda-api/
+│   ├── container.nix          # Container build logic (mkContainer, etc.)
+│   ├── configs/
+│   │   ├── colonelpanic/
+│   │   │   ├── custom-config.el
+│   │   │   └── overrides.el (optional)
+│   │   └── kat/
+│   │       └── custom-config.el
+│   ├── fly/
+│   │   ├── fly.toml
+│   │   ├── deploy.sh
+│   │   └── config-{instance}.env
+│   └── secrets/
+│       ├── secrets.nix        # agenix declarations
+│       └── *.age              # encrypted secrets
+└── dotfiles/emacs.d/
+    └── org-config.org         # Source of truth for org config
+```
+
+## Flake Integration
+
+The main dotfiles flake at `/home/imalison/dotfiles/nixos/flake.nix` exposes container outputs:
+
+```nix
+outputs = inputs @ { self, nixpkgs, flake-utils, ... }:
+  {
+    nixosConfigurations = { ... };  # existing
+  } // flake-utils.lib.eachDefaultSystem (system:
+    let
+      pkgs = import nixpkgs { inherit system; };
+      containerLib = import ../org-agenda-api/container.nix {
+        inherit pkgs system;
+        tangledConfig = (import ./org-agenda-api.nix {
+          inherit pkgs system;
+          inputs = inputs;
+        }).org-agenda-custom-config;
+      };
+    in {
+      packages = {
+        container-colonelpanic = containerLib.mkInstanceContainer "colonelpanic";
+        container-kat = containerLib.mkInstanceContainer "kat";
+      };
+    }
+  );
+```
+
+Build with: `nix build .#container-colonelpanic`
+
+## Custom Elisp & Tangling
+
+Single source of truth: `org-config.org` tangles to elisp files loaded by containers.
+
+**What stays in custom-config.el (container-specific glue):**
+- Path overrides (`/data/org` instead of `~/org`)
+- Stubs for unavailable packages (`org-bullets-mode` no-op)
+- Customize-to-setq format conversion
+- Template conversion for org-agenda-api format
+- Instance-specific settings
+
+**Audit:** During implementation, verify no actual org logic is duplicated in custom-config.el.
+
+## Cachix Integration
+
+### Phase 1: Use upstream cache as substituter
+
+Add to dotfiles flake's `nixConfig`:
+
+```nix
+nixConfig = {
+  extra-substituters = [
+    "https://org-agenda-api.cachix.org"
+  ];
+  extra-trusted-public-keys = [
+    "org-agenda-api.cachix.org-1:PUBLIC_KEY_HERE"
+  ];
+};
+```
+
+Benefits:
+- `container-base` (~500MB+ dependencies) fetched from cache
+- Rebuilds only process the small custom config layer
+
+### Phase 2 (future): Push custom builds
+
+Set up GitHub Action or local push for colonelpanic-specific container builds.
+
+## Fly.io Deployment
+
+**What moves:**
+- `fly.toml` → `dotfiles/org-agenda-api/fly/fly.toml`
+- `deploy.sh` → `dotfiles/org-agenda-api/fly/deploy.sh`
+- `configs/*/config.env` → `dotfiles/org-agenda-api/fly/config-{instance}.env`
+- Agenix secrets → `dotfiles/org-agenda-api/secrets/`
+
+**Deploy script changes:**
+- Build path: `nix build "../nixos#container-${INSTANCE}"`
+- Secrets path adjusts to new location
+- Otherwise same logic
+
+## Implementation Phases
+
+### Phase 1: Pull latest & verify current state
+- Pull latest changes in org-agenda-api and colonelpanic-org-agenda-api
+- Build container, verify it works
+- Fix any issues before restructuring
+
+### Phase 2: Create dotfiles structure
+- Create `/home/imalison/dotfiles/org-agenda-api/` directory
+- Move container.nix logic (adapted from current colonelpanic-org-agenda-api flake)
+- Move instance configs (colonelpanic/, kat/)
+- Move fly.io deployment files
+- Move agenix secrets
+
+### Phase 3: Integrate with dotfiles flake
+- Update `/home/imalison/dotfiles/nixos/flake.nix` to expose container outputs
+- Add cachix substituter configuration
+- Test build from dotfiles: `nix build .#container-colonelpanic`
+
+### Phase 4: Verify deployment
+- Test deploy.sh from new location
+- Verify fly.io deployment works
+- Run the container locally on a NixOS machine
+
+### Phase 5: Audit & cleanup
+- Review custom-config.el for any duplicated org logic
+- Archive colonelpanic-org-agenda-api repo
+- Update any references/documentation
+
+## Repos Affected
+
+- **dotfiles** - Receives container build + fly.io deployment
+- **colonelpanic-org-agenda-api** - Becomes obsolete after migration
+- **org-agenda-api** (upstream) - No changes, used as flake input