From 8498d382a5a8879cfd4dd2a093cd1811b8a79bc9 Mon Sep 17 00:00:00 2001 From: Greg Holmes Date: Fri, 23 Oct 2026 11:55:23 +0100 Subject: [PATCH 1/2] docs: refresh dx-stack guidance --- AGENTS.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f74bda71..85f7d16d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,26 +1,26 @@ # examples — Deepgram Code Examples -> **This app is part of the Deepgram DX stack.** When working in this repo, you must follow cross-stack documentation rules. A PostToolUse hook will remind you when you edit cross-stack files, but you are also responsible for catching changes the hook doesn't cover. +> **This app is part of the Deepgram DX stack.** When working in this repo, you must follow cross-stack documentation rules. ## DX Stack Rules 1. **Incremental changes, comprehensive reviews.** Make changes incrementally. But before finishing any task, do a comprehensive review to spot architectural misses — port conflicts, auth flow breakage, env var mismatches, or contract changes that affect other services. -2. **Update dx-stack docs when you change cross-stack behavior.** If your change affects ports, auth flows, env vars, redirect URIs, API contracts, or deployment config, update the reference docs at `/Users/lukeoliff/Projects/deepgram/dx-stack/` before finishing. +2. **Update dx-stack docs when you change cross-stack behavior.** If your change affects ports, auth flows, env vars, redirect URIs, API contracts, or deployment config, update the reference docs in your local checkout of https://github.com/deepgram/dx-stack before finishing. -3. **Know the architecture.** Read `/Users/lukeoliff/Projects/deepgram/dx-stack/CLAUDE.md` for the full stack context — port map, auth flows, service-to-service communication, and environment matrix. +3. **Know the architecture.** Read `AGENTS.md` and `docs/architecture.md` in your `dx-stack` checkout for the full stack context — port map, auth flows, service-to-service communication, and environment matrix. ### What requires dx-stack updates | Change | Update | |--------|--------| -| Port changes | `dx-stack/CLAUDE.md` port map + `docs/runbook.md` | +| Port changes | `dx-stack/AGENTS.md` port map + `dx-stack/data/ports.yaml` + `dx-stack/docs/runbook.md` | | Auth flow / session changes | `dx-stack/docs/auth.md` | -| OIDC client changes | `dx-stack/docs/auth.md` client table | -| Env var changes | `dx-stack/docs/environments.md` | -| New cross-service endpoints | `dx-stack/CLAUDE.md` cross-service section | -| Deployment / Fly config changes | `dx-stack/CLAUDE.md` deployment section | +| OIDC client changes | `dx-stack/data/oidc-clients.yaml` + `dx-stack/docs/auth.md` client table | +| Env var changes | `dx-stack/data/env-vars.yaml` + `dx-stack/docs/environments.md` | +| New cross-service endpoints | `dx-stack/AGENTS.md` cross-service section | +| Deployment / Fly config changes | `dx-stack/AGENTS.md` deployment section | | Database schema changes | `dx-stack/docs/auth.md` schema section | -| Redirect URI changes | `dx-stack/docs/auth.md` + seed.ts | +| Redirect URI changes | `dx-stack/data/oidc-clients.yaml` + `dx-stack/docs/auth.md` + seed.ts | Code examples demonstrating Deepgram API usage across languages. From f7947915a20c791c7c16bd1c48dd1436ef9ce075 Mon Sep 17 00:00:00 2001 From: Corey Weathers Date: Fri, 23 Oct 2026 07:22:15 -0400 Subject: [PATCH 2/2] docs: point stack context at AGENTS.md and docs/auth.md, name the dx-document-change skill docs/architecture.md in dx-stack is the design essay, not the port map or auth flows; those live in AGENTS.md and docs/auth.md. Also name the skill that replaced the deleted per-repo hook. --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 85f7d16d..a877d785 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,9 +6,9 @@ 1. **Incremental changes, comprehensive reviews.** Make changes incrementally. But before finishing any task, do a comprehensive review to spot architectural misses — port conflicts, auth flow breakage, env var mismatches, or contract changes that affect other services. -2. **Update dx-stack docs when you change cross-stack behavior.** If your change affects ports, auth flows, env vars, redirect URIs, API contracts, or deployment config, update the reference docs in your local checkout of https://github.com/deepgram/dx-stack before finishing. +2. **Update dx-stack docs when you change cross-stack behavior.** If your change affects ports, auth flows, env vars, redirect URIs, API contracts, or deployment config, update the reference docs in your local checkout of https://github.com/deepgram/dx-stack before finishing. The `dx-document-change` skill in dx-stack (loaded via the dx-stack MCP, see `dx-stack/docs/mcps.md`) walks through these updates and replaces the old per-repo hook; the table below is the manual fallback. -3. **Know the architecture.** Read `AGENTS.md` and `docs/architecture.md` in your `dx-stack` checkout for the full stack context — port map, auth flows, service-to-service communication, and environment matrix. +3. **Know the architecture.** Read `AGENTS.md` (port map, cross-service architecture, environments, deployment) and `docs/auth.md` (auth flows) in your `dx-stack` checkout for the full stack context. ### What requires dx-stack updates