CodeIssuesPull RequestsActionsSecurityInsights
✨ AI
More
Settings

chore(docs): keep all docs clean + green with a timestamp CI gate #4080

Merged⚡ AI-generatedXSccantynz wants to mergeclaude/docs-clean-and-greenmainopened Jun 8, 2026
49 changed files+285−8
Added.github/workflows/docs.yml+25−0View fileUnifiedSplit
1name: Docs
2
3on:
4 push:
5 branches: [main]
6 pull_request:
7
8permissions:
9 contents: read
10
11jobs:
12 docs-check:
13 name: Docs clean + green (timestamps)
14 runs-on: ubuntu-latest
15 steps:
16 - name: Checkout
17 uses: actions/checkout@v4
18
19 - name: Setup Bun
20 uses: oven-sh/setup-bun@v2
21 with:
22 bun-version: latest
23
24 - name: Check docs are stamped
25 run: bun run docs:check
ModifiedALECRAE-BRIEF.md+4−0View fileUnifiedSplit
287287- DNS pointed to Cloudflare
288288
289289**Or:** onboard to Crontech and handle it all there.
290
291---
292
293_Last updated: 2026-06-08 23:35 UTC_
ModifiedCLAUDE.md+3−2View fileUnifiedSplit
3232- Any doc file (`CLAUDE.md`, `docs/**`, `README`s, ADRs, runbooks) that is touched **must** have its `Last updated:` line refreshed in the same change, in the format `YYYY-MM-DD HH:MM UTC` (date AND time, not date alone).
3333- Docs are kept current on a **daily cadence** — if you work in a doc, it gets today's stamp. Stale stamps mean stale docs.
3434- The stamp is applied **on every edit** (when content changes), so the timestamp always reflects a real change — not a meaningless background bump.
35- **Enforced in CI:** `bun run docs:check` fails if any doc is missing a valid stamp (the `Docs` workflow gates every push + PR). Run `bun run docs:fix` to stamp/normalize. **Docs stay clean and green at all times.**
3536
3637---
3738
6696701. Update the "Build Status" section with what got done
6706712. Update the "Known Issues" section with anything discovered
6716723. Update the "Next Actions" section with what's next
6724. Update "Date last updated" at the bottom
6734. Update "Last updated" (date + time, UTC) at the bottom — run `bun run docs:check`
6736745. Commit and push everything
6746756. Leave the codebase in a runnable state
675676
729730
730731## 📅 STATUS
731732
732**Last updated:** 2026-06-08 23:28 UTC
733**Last updated:** 2026-06-08 23:36 UTC
733734**Current phase:** Phase 1 — Ready for Beta Launch
734735**Current focus:** Feature-complete build (84 features, 90 routes, 61 schemas, 290+ endpoints). Tier 6-8 AI platform features complete. Google sign-in + Vapron platform integration landed (PR #48). **Vapron is the permanent platform** (email, AI, storage, secrets, deploy) — Cloudflare/Vercel/Neon were always interim scaffolding until Vapron was built, and the app migrates onto Vapron as the target infra. The off-stack AWS EKS deploy pipeline has been removed. Production deployment awaiting Craig's Vapron + infra setup.
735736**Build completion:** TIER 1-4 (36/36) + 7 bonus + 31 advanced (S10/10 + A7/7 + B8/8 + C6/10) + 20 expansion (Tier 5) + 9 platform (Tier 6) + 6 intelligence (Tier 7) + 6 deep AI (Tier 8)
ModifiedGO_LIVE_GAPS.md+4−0View fileUnifiedSplit
132132- **Enterprise-sellable:** months away — gated on SOC 2 + load-testing, **not code**.
133133
134134*Update this file at the end of every session per the Bible Rule.*
135
136---
137
138_Last updated: 2026-06-08 23:35 UTC_
ModifiedLAUNCH_READINESS.md+4−0View fileUnifiedSplit
223223---
224224
225225*Generated by deep AI scan of `claude/launch-readiness-checklist-lVjmh`. Update this file at the end of every session per the Bible Rule.*
226
227---
228
229_Last updated: 2026-06-08 23:35 UTC_
ModifiedSECURITY.md+1−1View fileUnifiedSplit
107107
108108---
109109
110Last updated: 2026-04-16.
110_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/changelog/content/2026-04-05-launch.md+4−0View fileUnifiedSplit
4040- CRDT collaborative drafting
4141
4242Welcome to AlecRae.
43
44---
45
46_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/desktop/README.md+4−0View fileUnifiedSplit
8181CSC_LINK=path/to/cert.p12
8282CSC_KEY_PASSWORD=cert_password
8383```
84
85---
86
87_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/docs/content/authentication.md+4−0View fileUnifiedSplit
3838## Never commit keys
3939
4040Use environment variables or a secrets manager. AlecRae scans public GitHub for leaked keys and revokes them automatically.
41
42---
43
44_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/docs/content/domains.md+4−0View fileUnifiedSplit
4242```
4343
4444Pending and queued messages from that domain are cancelled immediately.
45
46---
47
48_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/docs/content/errors.md+4−0View fileUnifiedSplit
4545## Retry guidance
4646
4747Retry on `429`, `500`, `502`, `503`, `504`. Use exponential backoff starting at 1 s, doubling each attempt, with full jitter, capped at 60 s. Include an `Idempotency-Key` header so retries don't double-send.
48
49---
50
51_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/docs/content/messages.md+4−0View fileUnifiedSplit
6666```
6767
6868Returns the current state: `queued`, `sending`, `delivered`, `bounced`, `complained`, or `failed`.
69
70---
71
72_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/docs/content/migrate-apple-mail.md+4−0View fileUnifiedSplit
143143- [Set up keyboard shortcuts](/quickstart) to navigate AlecRae efficiently
144144- [Explore AI Compose](/messages) to draft emails faster
145145- [Configure Smart Inbox](/webhooks) for automatic email categorization
146
147---
148
149_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/docs/content/migrate-gmail.md+4−0View fileUnifiedSplit
118118- [Set up keyboard shortcuts](/quickstart) to navigate AlecRae like a power user
119119- [Configure AI Compose](/messages) to draft emails in your writing style
120120- [Explore Smart Inbox](/webhooks) to let AlecRae automatically categorize your email
121
122---
123
124_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/docs/content/migrate-outlook.md+4−0View fileUnifiedSplit
121121- [Set up keyboard shortcuts](/quickstart) to navigate AlecRae like a power user
122122- [Configure AI Compose](/messages) to draft emails in your writing style
123123- [Set up E2E encryption](/authentication) for sensitive communications
124
125---
126
127_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/docs/content/quickstart.md+4−0View fileUnifiedSplit
4242- [Authentication](/authentication) — API keys, scopes, and bearer tokens
4343- [Messages](/messages) — All the ways to send mail
4444- [Errors](/errors) — Status codes and retry guidance
45
46---
47
48_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/docs/content/webhooks.md+4−0View fileUnifiedSplit
6262## Retries
6363
6464AlecRae retries failed deliveries with exponential backoff for up to 24 hours. Respond with a 2xx status to acknowledge.
65
66---
67
68_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/mobile/README.md+4−0View fileUnifiedSplit
8484- **iOS:** Apple Developer account ($99/yr)
8585- **Android:** Google Play Developer account ($25 one-time)
8686- **Push notifications:** Apple APNs key + Firebase FCM server key
87
88---
89
90_Last updated: 2026-06-08 23:35 UTC_
Modifiedapps/web/STANDALONE_ARCHITECTURE.md+4−0View fileUnifiedSplit
5151- API p99: < 200ms
5252- AI compose first token: < 500ms (Haiku edge)
5353- Search results: < 50ms (Meilisearch local index)
54
55---
56
57_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/VISION.md+4−0View fileUnifiedSplit
136136works for you.
137137
138138This is not just a business. This is a legacy.
139
140---
141
142_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/api/authentication.md+4−0View fileUnifiedSplit
157157 }
158158}
159159```
160
161---
162
163_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/api/errors.md+4−0View fileUnifiedSplit
168168 }
169169}
170170```
171
172---
173
174_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/api/rate-limits.md+4−0View fileUnifiedSplit
117117```
118118
119119The response includes cumulative send counts for the current billing period.
120
121---
122
123_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/architecture/defensible-innovations.md+4−0View fileUnifiedSplit
185185 client library, SDK) to build ecosystem and developer adoption
186186- Keep core AI, Sentinel, and reputation engines proprietary
187187- Open protocols, closed intelligence
188
189---
190
191_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/compliance/soc2/README.md+1−1View fileUnifiedSplit
22
33> **Owner:** Craig (ccantynz@gmail.com)
44> **Status:** Pre-audit groundwork — Type I target
5> **Last updated:** 2026-06-08
5_Last updated: 2026-06-08 23:35 UTC_
66
77---
88
Modifieddocs/compliance/soc2/controls-matrix.md+1−1View fileUnifiedSplit
11# SOC 2 Controls Matrix — AlecRae
22
3> **Last updated:** 2026-06-08
3_Last updated: 2026-06-08 23:35 UTC_
44> **Scope:** Security (CC), Availability (A), Confidentiality (C)
55> **Status key:** Implemented | Partial | Missing
66
Modifieddocs/compliance/soc2/gap-analysis.md+1−1View fileUnifiedSplit
11# SOC 2 Gap Analysis — AlecRae
22
3> **Last updated:** 2026-06-08
3_Last updated: 2026-06-08 23:35 UTC_
44> **Based on:** controls-matrix.md audit of codebase, CLAUDE.md, SECURITY.md, and GitHub workflows
55> **Audience:** Craig + any readiness consultant or auditor
66
Modifieddocs/compliance/soc2/policy-templates/access-control-policy.md+4−0View fileUnifiedSplit
202202**Title:** Founder & CEO, AlecRae
203203**Signature:** ________________________
204204**Date:** [INSERT DATE]
205
206---
207
208_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/compliance/soc2/policy-templates/bcp-dr-plan.md+4−0View fileUnifiedSplit
255255**Title:** Founder & CEO, AlecRae
256256**Signature:** ________________________
257257**Date:** [INSERT DATE]
258
259---
260
261_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/compliance/soc2/policy-templates/change-management-policy.md+4−0View fileUnifiedSplit
217217**Title:** Founder & CEO, AlecRae
218218**Signature:** ________________________
219219**Date:** [INSERT DATE]
220
221---
222
223_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/compliance/soc2/policy-templates/incident-response-plan.md+4−0View fileUnifiedSplit
280280**Title:** Founder & CEO, AlecRae
281281**Signature:** ________________________
282282**Date:** [INSERT DATE]
283
284---
285
286_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/compliance/soc2/policy-templates/information-security-policy.md+4−0View fileUnifiedSplit
236236
237237*See also: Access Control Policy, Incident Response Plan, Change Management Policy,
238238Vendor Management Policy, Business Continuity / DR Plan*
239
240---
241
242_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/compliance/soc2/policy-templates/vendor-management-policy.md+4−0View fileUnifiedSplit
165165**Title:** Founder & CEO, AlecRae
166166**Signature:** ________________________
167167**Date:** [INSERT DATE]
168
169---
170
171_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/fbl-setup.md+4−0View fileUnifiedSplit
120120 +-- Check complaint rate
121121 +-- Auto-throttle if rate > 0.1%
122122```
123
124---
125
126_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/guides/contributing.md+4−0View fileUnifiedSplit
219219## Questions?
220220
221221If you have questions about contributing, open a GitHub Discussion or reach out to the maintainers.
222
223---
224
225_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/guides/deployment.md+4−0View fileUnifiedSplit
283283- [ ] Backup strategy is in place and tested
284284- [ ] Rate limiting is configured on public endpoints
285285- [ ] IP warm-up plan is prepared for new sending IPs
286
287---
288
289_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/guides/getting-started.md+4−0View fileUnifiedSplit
175175- Read the [Deployment Guide](./deployment.md) for production setup.
176176- Read the [Contributing Guide](./contributing.md) for development workflow.
177177- Review the architecture in `CLAUDE.md` at the repository root.
178
179---
180
181_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/infra/craig-go-live.md+4−0View fileUnifiedSplit
274274- [`env-audit.md`](./env-audit.md)
275275- [`.env.production.template`](./.env.production.template)
276276- [`deliverability.md`](./deliverability.md)
277
278---
279
280_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/infra/craig-send-today.md+4−0View fileUnifiedSplit
193193---
194194
195195*Pinned 2026-05-08. Update this file after Day 90 graduation, or if SES region/identity changes.*
196
197---
198
199_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/infra/deliverability.md+4−0View fileUnifiedSplit
166166---
167167
168168*This runbook is the source of truth for AlecRae deliverability operations. Updates require review against live Postmaster Tools and FBL data.*
169
170---
171
172_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/infra/dns-zone-alecrae.md+4−0View fileUnifiedSplit
196196- You are now fully protected. Spoofers get rejected outright. Legitimate mail has been verified for 60 days.
197197
198198**If at any stage reports show a problem, pause the progression and fix the sender before tightening further.**
199
200---
201
202_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/infra/env-audit.md+1−1View fileUnifiedSplit
22
33> Source of truth for production env vars across web, api, mta, admin, and mobile.
44> Pairs with `.env.production.template` in this same directory.
5> Last updated: 2026-04-18.
5_Last updated: 2026-06-08 23:35 UTC_
66
77---
88
Modifieddocs/infra/fly-mta-deploy.md+1−1View fileUnifiedSplit
277277
278278---
279279
280**Last updated:** 2026-04-18
280_Last updated: 2026-06-08 23:35 UTC_
281281**Owner:** Craig (escalate infra changes per CLAUDE.md Boss Rule)
Modifieddocs/infra/neon-setup.md+4−0View fileUnifiedSplit
200200**Beyond Scale:** Usage-based. Budget alerts live under **Billing → Alerts**. Set one at $50/mo to start.
201201
202202Ping Craig before moving to any paid tier — infra spend is a Boss-Rule item.
203
204---
205
206_Last updated: 2026-06-08 23:35 UTC_
Modifieddocs/infra/upstash-setup.md+4−0View fileUnifiedSplit
158158Set a budget alert: Console → **Account****Billing****Alerts** → $25/mo initial.
159159
160160Ping Craig before approving any auto-upgrade — infra spend is a Boss-Rule item.
161
162---
163
164_Last updated: 2026-06-08 23:35 UTC_
Modifiedload-tests/README.md+4−0View fileUnifiedSplit
254254 ├── read-heavy.js ← admin stats, admin messages, list emails, heatmap
255255 └── full-suite.js ← combined mixed-traffic simulation
256256```
257
258---
259
260_Last updated: 2026-06-08 23:35 UTC_
Modifiedpackage.json+2−0View fileUnifiedSplit
1818 "clean": "turbo run clean",
1919 "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
2020 "preflight": "bun run scripts/preflight.ts",
21 "docs:check": "bun run scripts/check-docs.ts",
22 "docs:fix": "bun run scripts/check-docs.ts --fix",
2123 "db:migrate": "bun run packages/db/src/migrate.ts",
2224 "db:seed": "bun run packages/db/src/seed.ts",
2325 "db:generate": "bun run --cwd packages/db db:generate",
Addedscripts/check-docs.ts+93−0View fileUnifiedSplit
1#!/usr/bin/env bun
2/**
3 * Docs governance check — keeps documentation "clean and green at all times".
4 *
5 * Enforces THE TIMESTAMP RULE (see CLAUDE.md): every documentation file must
6 * carry a `Last updated: YYYY-MM-DD HH:MM UTC` stamp. This guards presence +
7 * format (which is stable and stays green) rather than requiring "today's"
8 * date, which would falsely fail every PR that doesn't touch docs.
9 *
10 * Usage:
11 * bun run scripts/check-docs.ts # check; exits 1 on any violation
12 * bun run scripts/check-docs.ts --fix # add/normalize stamps in place
13 */
14
15import { Glob } from "bun";
16
17// Files that are not prose docs and are exempt from the stamp rule.
18const IGNORE = new Set<string>([".github/pull_request_template.md"]);
19
20const IGNORE_DIRS = ["node_modules", ".git", ".next", "dist", ".turbo"];
21
22// Canonical stamp matcher — tolerates markdown emphasis (** or _) around it.
23const STAMP_RE = /Last updated:\**\s*_?\s*\d{4}-\d{2}-\d{2} \d{2}:\d{2} UTC/;
24
25// Matches any pre-existing (possibly malformed) stamp line to normalize.
26const EXISTING_LINE_RE = /^.*\**(?:Date last updated|Last updated):.*$/im;
27
28function nowStamp(): string {
29 const d = new Date();
30 const pad = (n: number): string => String(n).padStart(2, "0");
31 return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(
32 d.getUTCHours(),
33 )}:${pad(d.getUTCMinutes())} UTC`;
34}
35
36async function listDocs(): Promise<string[]> {
37 const glob = new Glob("**/*.md");
38 const out: string[] = [];
39 for await (const file of glob.scan({ cwd: process.cwd(), dot: false })) {
40 if (IGNORE_DIRS.some((d) => file.split("/").includes(d))) continue;
41 if (IGNORE.has(file)) continue;
42 out.push(file);
43 }
44 return out.sort();
45}
46
47function applyStamp(content: string, stamp: string): string {
48 const canonical = `_Last updated: ${stamp}_`;
49 // Normalize an existing (non-compliant) stamp line if present.
50 if (EXISTING_LINE_RE.test(content)) {
51 return content.replace(EXISTING_LINE_RE, canonical);
52 }
53 // Otherwise append a footer stamp.
54 const trimmed = content.replace(/\s+$/, "");
55 return `${trimmed}\n\n---\n\n${canonical}\n`;
56}
57
58async function main(): Promise<void> {
59 const fix = process.argv.includes("--fix");
60 const docs = await listDocs();
61 const stamp = nowStamp();
62 const violations: string[] = [];
63
64 for (const file of docs) {
65 const content = await Bun.file(file).text();
66 if (STAMP_RE.test(content)) continue;
67
68 if (fix) {
69 await Bun.write(file, applyStamp(content, stamp));
70 console.log(`stamped: ${file}`);
71 } else {
72 violations.push(file);
73 }
74 }
75
76 if (fix) {
77 console.log(`\n✓ Docs check: stamped ${docs.length} files scanned.`);
78 return;
79 }
80
81 if (violations.length > 0) {
82 console.error(
83 `✗ Docs check failed: ${violations.length} file(s) missing a valid "Last updated: YYYY-MM-DD HH:MM UTC" stamp:\n`,
84 );
85 for (const v of violations) console.error(` - ${v}`);
86 console.error(`\nRun \`bun run docs:fix\` to stamp them.`);
87 process.exit(1);
88 }
89
90 console.log(`✓ Docs check passed: ${docs.length} docs all carry a valid timestamp.`);
91}
92
93await main();
Modifiedservices/imap/TODO.md+4−0View fileUnifiedSplit
6060
6161Until then the IMAP service is **wired but not bootable** — the auth
6262and mailbox handlers compile cleanly, but no one starts a TCP listener.
63
64---
65
66_Last updated: 2026-06-08 23:35 UTC_
6367
c comment · e edit title · m merge · a approve · r request changes · ? shortcuts