Repository documentation is the authoritative source for engineering
technical knowledge — architecture, conventions, runbooks, pipelines. See
docs/github-source-of-truth.md section 1
for the exact system-ownership boundary this follows, and section 7 for what
must never appear here (secrets, customer-private data, pricing, contracts,
commercial roadmap).
This page exists so an implementation agent can find the right doc without
grepping the directory. If you add a new docs/** file, add a row here.
- New to the system? Read
docs/architecture/overview.mdfirst. - Engineering lifecycle, agent-ready criteria, and PR linking:
docs/github-source-of-truth.md. - Human checklist (GitHub protection, Azure IDs, npm):
SETUP.md. - Day-to-day agent workflow:
AGENTS.md.
docs/
├── README.md (this file)
├── github-source-of-truth.md (engineering lifecycle policy)
├── github-project.md (Project fields, views, labels)
├── pr-pipelines.md (CI, release, secrets)
├── email-forward-email.md (Forward Email runtime + provision CLI)
├── architecture/
│ ├── overview.md (phase-1 system shape)
│ ├── request-lifecycle.md (POST /emails/send sequence + error codes)
│ ├── template-lifecycle.md (source -> compile -> publish -> Blob -> send)
│ └── multi-tenant-security.md (tenant + environment boundaries)
├── guides/
│ ├── template-authoring.md (consumer template source files + variables)
│ ├── template-publishing.md (post-kit-publish, blob layout, environments)
│ ├── editor-integration.md (embed @singleton-sd/post-kit-editor in admin UIs)
│ ├── api-quickstart.md (send API + client quick start)
│ ├── mcp.md (MCP /mcp endpoint: tools, auth, local + deployed clients)
│ ├── packages.md (install, pin, upgrade @singleton-sd/post-kit-*)
│ └── public-forms.md (public web forms: trusted server endpoint pattern)
├── integrations/
│ └── inkads-marketing.md (InkAds PoC site → POST /contact)
├── onboarding/
│ ├── tenant-onboarding.md (new tenant → first email)
│ ├── contact-consumer.md (new marketing/contact consumer checklist)
│ └── environments.md (dev/staging/prod separation, local dev)
├── operations/
│ ├── troubleshooting.md (send endpoint triage, correlation IDs, runbooks)
│ ├── send-metrics-queries.md (Kusto queries for send telemetry)
│ ├── releasing.md (release.yml bump + OIDC npm publish checklist)
│ └── learnings-contact-cors-custom-domain.md (CORS dual-allowlist, contact 500, custom domain, agent handoff)
└── examples/
└── publish-email-templates.yml (sample consumer publish workflow)
| Doc | Covers |
|---|---|
github-source-of-truth.md |
Engineering system-of-record policy |
github-project.md |
PostKit Engineering project fields, views, labels |
pr-pipelines.md |
PR CI, release, secrets policy |
architecture/overview.md |
Phase-1 architecture: Functions API, EmailProvider, consumers |
email-forward-email.md |
Forward Email provider, DNS, pnpm email:provision, Function contact, branding CI |
guides/api-quickstart.md |
POST /emails/send contract, PostKitClient usage, error taxonomy and retries |
guides/mcp.md |
Stateless POST /mcp Streamable HTTP adapter, template tools, Principal + scopes (PoC TENANT_KEY_MAP), local + deployed client config |
guides/packages.md |
Install, pin, upgrade published @singleton-sd/post-kit-* packages; semver and compatibility |
guides/template-authoring.md |
Consumer template layout, metadata.json fields, template keys, variables, local validation |
guides/template-publishing.md |
post-kit-publish flags, blob layout, fail-fast, per-environment promotion, OIDC + RBAC |
guides/editor-integration.md |
Embed @singleton-sd/post-kit-editor: install, onSave persistence, preview vs send, access control |
examples/publish-email-templates.yml |
Sample consumer-repository publish workflow (not installed in this repo) |
onboarding/tenant-onboarding.md |
New tenant from nothing configured to first email: identifier, credential, sender, templates, publish, test send, triage |
onboarding/contact-consumer.md |
New marketing/contact consumer: App Config origins + host profile, platform CORS, optional mail domain, publicBaseUrl, preview header, smoke tests |
onboarding/environments.md |
development/staging/production separation, local development without real delivery |
architecture/request-lifecycle.md |
POST /emails/send runtime sequence, correlation IDs, error-code → HTTP-status table |
architecture/template-lifecycle.md |
Template source → compiler → publisher → Blob layout → send-time load |
architecture/multi-tenant-security.md |
Tenant resolution, environment separation, path safety, credential boundaries, unimplemented controls |
operations/troubleshooting.md |
POST /emails/send error triage, correlation-ID tracing, incident runbooks |
operations/send-metrics-queries.md |
Kusto queries for send volume, success rate, provider failures, latency, duplicates |
operations/releasing.md |
release.yml triggers, path-aware bumps, OIDC Trusted Publishing, maintainer checklist |
guides/public-forms.md |
Public web forms (Contact Us, waitlist): trusted server endpoint pattern, credential-exposure anti-patterns, consumer-side validation / abuse / rate-limit duties |
integrations/inkads-marketing.md |
InkAds PoC site → POST /contact integration |