Skip to content

docs: refresh dx-stack guidance #359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GregHolmes merged 2 commits into from
Oct 23, 2026
Merged

docs: refresh dx-stack guidance #359

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8498d38
docs: refresh dx-stack guidance
GregHolmes Oct 23, 2026
f794791
docs: point stack context at AGENTS.md and docs/auth.md, name the dx-…
dg-coreylweathers Oct 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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. 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 `/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` (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

| 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.
Loading