Harden and review the main codebase

.env.example

@@ -5,5 +5,6 @@
 
 # Browser-assisted imports are disabled by default. Enable only for local
 # development with a random token that is also configured in the extension.
+# Generate one with `openssl rand -hex 32`; weak tokens are rejected.
 TRAUMA_BROWSER_IMPORT_ENABLED=false
 TRAUMA_BROWSER_IMPORT_TOKEN=

.github/workflows/ci.yml

@@ -9,6 +9,7 @@ on:
       - "src/**"
       - "tests/**"
       - "e2e/**"
+      - "extensions/**"
       - "public/**"
       - "drizzle/**"
       - "scripts/**"
@@ -20,6 +21,7 @@ on:
       - "package.json"
       - "bun.lock"
       - "mise.toml"
+      - ".env.example"
       - "trauma.config.example.json"
   pull_request:
     branches:
@@ -29,6 +31,7 @@ on:
       - "src/**"
       - "tests/**"
       - "e2e/**"
+      - "extensions/**"
       - "public/**"
       - "drizzle/**"
       - "scripts/**"
@@ -40,6 +43,7 @@ on:
       - "package.json"
       - "bun.lock"
       - "mise.toml"
+      - ".env.example"
       - "trauma.config.example.json"
   workflow_dispatch:
 
@@ -58,21 +62,37 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
 
       - name: Set up Bun
-        uses: oven-sh/setup-bun@v2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version: 1.3.13
 
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Audit dependencies
+        run: bun run audit
+
       - name: Run baseline verification
         run: bun run verify
 
       - name: Install Playwright browser
         run: bunx playwright install --with-deps chromium
 
-      - name: Run E2E smoke tests
+      - name: Run E2E tests
         run: bun run test:e2e
+
+      - name: Upload Playwright failure artifacts
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          if-no-files-found: ignore
+          name: playwright-failures-${{ github.run_id }}-${{ github.run_attempt }}
+          path: |
+            playwright-report/
+            test-results/
+          retention-days: 7

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/docs.yml"
+      - "docs/**"
+      - "AGENTS.md"
+      - "Backlog.md"
+      - "CLAUDE.md"
+      - "README.md"
+      - "scripts/check-docs.ts"
+      - "package.json"
+  pull_request:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/docs.yml"
+      - "docs/**"
+      - "AGENTS.md"
+      - "Backlog.md"
+      - "CLAUDE.md"
+      - "README.md"
+      - "scripts/check-docs.ts"
+      - "package.json"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Check documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.13
+
+      - name: Check documentation
+        run: bun run docs:check

.github/workflows/release.yml

@@ -7,87 +7,136 @@ on:
       - "v*.*.*"
 
 permissions:
-  contents: write
+  contents: read
 
 concurrency:
   group: release-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
-  release:
-    name: Create GitHub Release
+  validate:
+    name: Validate release tag
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 5
+    outputs:
+      tag_name: ${{ steps.release_tag.outputs.tag_name }}
+      valid: ${{ steps.release_tag.outputs.valid }}
+      version: ${{ steps.release_tag.outputs.version }}
 
     steps:
+      - name: Check out tagged commit
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+          ref: ${{ github.sha }}
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.13
+
       - name: Validate release tag
         id: release_tag
-        shell: bash
-        run: |
-          TAG_NAME="${GITHUB_REF_NAME}"
+        run: bun run scripts/validate-release.ts
 
-          if [[ ! "$TAG_NAME" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "::notice title=Skipped release::Tag '$TAG_NAME' is not a three-part semantic version."
-            echo "valid=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
+  verify:
+    name: Verify release
+    needs: validate
+    if: needs.validate.outputs.valid == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
 
-          echo "valid=true" >> "$GITHUB_OUTPUT"
-          echo "tag_name=$TAG_NAME" >> "$GITHUB_OUTPUT"
-          echo "version=${TAG_NAME#v}" >> "$GITHUB_OUTPUT"
+    steps:
 
       - name: Check out repository
-        if: steps.release_tag.outputs.valid == 'true'
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ github.sha }}
 
       - name: Set up Bun
-        if: steps.release_tag.outputs.valid == 'true'
-        uses: oven-sh/setup-bun@v2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version: 1.3.13
 
       - name: Install dependencies
-        if: steps.release_tag.outputs.valid == 'true'
         run: bun install --frozen-lockfile
 
+      - name: Audit dependencies
+        run: bun run audit
+
       - name: Run baseline verification
-        if: steps.release_tag.outputs.valid == 'true'
         run: bun run verify
 
       - name: Install Playwright browser
-        if: steps.release_tag.outputs.valid == 'true'
         run: bunx playwright install --with-deps chromium
 
-      - name: Run E2E smoke tests
-        if: steps.release_tag.outputs.valid == 'true'
+      - name: Run E2E tests
         run: bun run test:e2e
 
+      - name: Upload Playwright failure artifacts
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          if-no-files-found: ignore
+          name: playwright-failures-${{ github.run_id }}-${{ github.run_attempt }}
+          path: |
+            playwright-report/
+            test-results/
+          retention-days: 7
+
+  release:
+    name: Create GitHub Release
+    needs: [validate, verify]
+    if: needs.validate.outputs.valid == 'true' && needs.verify.result == 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out tagged commit
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+          ref: ${{ github.sha }}
+
       - name: Create release
-        if: steps.release_tag.outputs.valid == 'true'
         env:
           GH_TOKEN: ${{ github.token }}
-          TAG_NAME: ${{ steps.release_tag.outputs.tag_name }}
-          RELEASE_VERSION: ${{ steps.release_tag.outputs.version }}
+          TAG_NAME: ${{ needs.validate.outputs.tag_name }}
+          RELEASE_VERSION: ${{ needs.validate.outputs.version }}
         run: |
           if gh release view "$TAG_NAME" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
             echo "Release $TAG_NAME already exists."
             exit 0
           fi
 
-          RELEASE_NOTES_FILE="changelog/v${RELEASE_VERSION}.md"
+          RELEASE_NOTES_PATH="changelog/v${RELEASE_VERSION}.md"
+
+          if [[ -f "$RELEASE_NOTES_PATH" ]]; then
+            if [[ ! -r "$RELEASE_NOTES_PATH" ]]; then
+              echo "::error title=Invalid release notes path::$RELEASE_NOTES_PATH is not readable."
+              exit 1
+            fi
 
-          if [[ -f "$RELEASE_NOTES_FILE" ]]; then
             gh release create "$TAG_NAME" \
               --repo "$GITHUB_REPOSITORY" \
               --title "TRAUMA $RELEASE_VERSION" \
-              --notes-file "$RELEASE_NOTES_FILE" \
+              --notes-file "$RELEASE_NOTES_PATH" \
               --verify-tag
-          else
+          elif [[ ! -e "$RELEASE_NOTES_PATH" && ! -L "$RELEASE_NOTES_PATH" ]]; then
             gh release create "$TAG_NAME" \
               --repo "$GITHUB_REPOSITORY" \
               --title "TRAUMA $RELEASE_VERSION" \
               --generate-notes \
               --verify-tag
+          else
+            echo "::error title=Invalid release notes path::$RELEASE_NOTES_PATH is not a regular file."
+            exit 1
           fi

.gitignore

@@ -1,5 +1,8 @@
 .superpowers/
 .eda/
+.tmp/
+app.config.timestamp_*.js
+.claude/settings.local.json
 node_modules/
 .vinxi/
 .output/

AGENTS.md

@@ -3,26 +3,13 @@
 Trauma is a TypeScript bookmark management app. The project domain term is
 `memory` for one bookmark and `memories` for the collection.
 
-## Documentation Map
+Start with [docs/INDEX.md](docs/INDEX.md). It is the authoritative map for
+current architecture, contracts, operations, and verification. Historical
+records are context only and must not override current semantic docs, code, or
+tests.
 
-Start with [docs/INDEX.md](docs/INDEX.md).
-
-Key project decisions are split by purpose:
-
-- Architecture: [docs/architecture/overview.md](docs/architecture/overview.md)
-- Data and storage: [docs/architecture/data-and-storage.md](docs/architecture/data-and-storage.md)
-- Runtime flows: [docs/architecture/flows.md](docs/architecture/flows.md)
-- UI and routing: [docs/architecture/ui-and-routing.md](docs/architecture/ui-and-routing.md)
-- Technology stack: [docs/references/technology-stack.md](docs/references/technology-stack.md)
-- Configuration: [docs/references/configuration.md](docs/references/configuration.md)
-- Coding standards: [docs/references/coding-standards/INDEX.md](docs/references/coding-standards/INDEX.md)
-- Glossary: [docs/references/glossary.md](docs/references/glossary.md)
-- Operations: [docs/operations/local-self-hosting.md](docs/operations/local-self-hosting.md)
-- Verification: [docs/quality/verification.md](docs/quality/verification.md)
-- Execution workflows: [docs/workflows/README.md](docs/workflows/README.md)
-
-The approved foundation design record is
-[docs/superpowers/specs/2026-05-09-trauma-foundation-design.md](docs/superpowers/specs/2026-05-09-trauma-foundation-design.md).
+Open durable work belongs in [Backlog.md](Backlog.md). Keep task-specific plans
+temporary and move lasting requirements into the owning semantic document.
 
 Commit finalization exclusions for Sawyer live in
 [.sawyer/exclude-whitelist.txt](.sawyer/exclude-whitelist.txt).

Backlog.md

@@ -0,0 +1,7 @@
+# Backlog
+
+This file contains durable open outcomes only. Keep it under 20 items, remove
+completed items, and put current behavior in semantic docs rather than expanding
+this file into implementation plans.
+
+No durable open outcomes are currently recorded.