[operations] docs: add observability assessment, site diagnostic runbook, and incident templates

.github/ISSUE_TEMPLATE/incident_report.md

@@ -0,0 +1,25 @@
+---
+name: Operational Incident Report
+about: Report an operational incident, build failure, or site outage
+title: '[INCIDENT] <Brief Summary>'
+labels: 'incident'
+assignees: ''
+---
+
+## Summary
+- **Severity Level**: SEV-1 / SEV-2 / SEV-3
+- **Impacted Systems**: Documentation site, Build Pipeline, Deployment Edge
+- **Time Detected**: YYYY-MM-DD HH:MM UTC
+
+## Impact Description
+Describe the customer or developer impact caused by this incident.
+
+## Diagnostic Evidence
+- **Workflow Run Link**:
+- **Log Snippet**:
+- **Observed Behavior**:
+
+## Mitigation & Recovery Steps
+- [ ] Initial triage completed
+- [ ] Workaround or rollback applied
+- [ ] Root cause identified and tracked

.github/ISSUE_TEMPLATE/postmortem.md

@@ -0,0 +1,25 @@
+---
+name: Operational Postmortem
+about: Postmortem review template for operational incidents
+title: '[POSTMORTEM] <Incident Title>'
+labels: 'postmortem'
+assignees: ''
+---
+
+## Incident Summary
+- **Date**: YYYY-MM-DD
+- **Duration**: XX minutes
+- **Severity**: SEV-1 / SEV-2
+
+## Timeline
+- **HH:MM UTC**: Incident detected
+- **HH:MM UTC**: Mitigation applied
+- **HH:MM UTC**: Resolution confirmed
+
+## Root Cause Analysis
+Detailed explanation of why the failure occurred.
+
+## Action Items
+- [ ] Preventative fix implemented
+- [ ] Runbook updated
+- [ ] Monitoring / lint checks enhanced

docs/observability.md

@@ -0,0 +1,28 @@
+# Operational Observability Assessment and Telemetry Guidelines
+
+This document outlines the observability posture and build diagnostic rules for the `tuna-os/docs` website.
+
+## Observability Posture and Architecture
+
+The `tuna-os/docs` site uses Docusaurus. It builds static assets deployed to edge nodes.
+
+### Log Streams and Diagnostic Data
+
+- **Build Logs**: Output from static compilation, TypeScript type checks, and link validation in GitHub Actions.
+- **Client Console Logs**: Browser console errors and warnings from React components or search scripts.
+- **Edge Deployment**: Status codes and traffic metrics from edge providers.
+
+## Managed Observability Backend Status
+
+Operator configuration status:
+- Open source backend: None configured.
+- Kube-native backend: None configured.
+- Commercial backend: None configured.
+
+This repository contains no external telemetry exporters, metrics collectors, or third-party scripts.
+
+## Incident and Operational Diagnostics
+
+Follow these steps for site errors or build failures:
+- Check logs in `.github/workflows/` for build step failures.
+- Read `runbooks/site-diagnostics.md` for triage procedures and escalation paths.

runbooks/site-diagnostics.md

@@ -0,0 +1,32 @@
+# Runbook: Documentation Site Diagnostics & Triage
+
+## Severity & Triage Quick Reference
+
+| Level | Condition | Response Time | Action |
+|-------|-----------|---------------|--------|
+| SEV-1 | Documentation site offline / 5xx on edge routes | < 30 min | Revert last deployment / verify edge worker status |
+| SEV-2 | Build pipeline failing on main branch | < 2 hours | Fix broken markdown/links or roll back failing PR |
+| SEV-3 | Broken internal link or asset rendering issue | Next business day | File issue and schedule PR fix |
+
+## Triage Procedure
+
+### 1. Build & Lint Verification
+When a deployment fails or build workflow errors:
+```bash
+npm ci
+just preflight
+```
+Inspect output for:
+- TypeScript compilation errors (`tsc`)
+- Missing or malformed MDX components
+- Broken relative image or document paths
+
+### 2. Edge & Deployment Verification
+If static site assets fail to serve:
+- Check Cloudflare Pages / deployment provider dashboard for build status.
+- Verify DNS and custom domain SSL certificate provisioning.
+- Confirm `docusaurus.config.ts` base URL and url settings match the target environment.
+
+### 3. Escalation Procedure
+- File an incident using `.github/ISSUE_TEMPLATE/incident_report.md`.
+- Notify documentation maintainers via release channel.