chore: init core docs including architecture decision records and initial specs

.editorconfig

@@ -7,4 +7,3 @@ insert_final_newline = true
 indent_style = space
 indent_size = 2
 trim_trailing_whitespace = true
-

.env.example

@@ -5,3 +5,11 @@
 # This repo also falls back to `OPENAI_API_KEY` for convenience.
 CODEX_API_KEY=
 OPENAI_API_KEY=
+
+# MCP config (SPEC 010)
+# Either point to a JSON config file, or provide an inline JSON string.
+#
+# CODEX_TOOLLOOP_MCP_CONFIG_JSON='{"servers":{...},"bundles":{...}}'
+# CODEX_TOOLLOOP_MCP_CONFIG_PATH=./codex-toolloop.mcp.json
+CODEX_TOOLLOOP_MCP_CONFIG_JSON=
+CODEX_TOOLLOOP_MCP_CONFIG_PATH=

.github/actions/ci-setup/action.yml

@@ -0,0 +1,25 @@
+name: CI Setup
+description: "Shared CI setup: pnpm, node, install (requires prior checkout)"
+
+inputs:
+  node-version-file:
+    description: "Path to node version file (default: package.json)"
+    required: false
+    default: "package.json"
+  pnpm-version:
+    description: "pnpm version to install (default: 10.28.1)"
+    required: false
+    default: "10.28.1"
+
+runs:
+  using: composite
+  steps:
+    - uses: pnpm/action-setup@v3
+      with:
+        version: ${{ inputs.pnpm-version }}
+    - uses: actions/setup-node@v4
+      with:
+        node-version-file: ${{ inputs.node-version-file }}
+        cache: pnpm
+    - run: pnpm install --frozen-lockfile
+      shell: bash

.github/codeql/codeql-config.yml

@@ -0,0 +1,6 @@
+name: "CodeQL Config"
+
+disable-default-queries: false
+
+queries:
+  - uses: security-extended

.github/dependabot.yml

@@ -0,0 +1,30 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "friday"
+      time: "04:00"
+    groups:
+      dev-dependencies:
+        patterns:
+          - "*"
+        dependency-type: "development"
+        update-types:
+          - "minor"
+          - "patch"
+      production-dependencies:
+        patterns:
+          - "*"
+        dependency-type: "production"
+        update-types:
+          - "minor"
+          - "patch"
+    commit-message:
+      prefix: "chore(deps)"
+      prefix-development: "chore(deps-dev)"
+    ignore:
+      - dependency-name: "@types/node"
+        update-types: ["version-update:semver-major"]
+    open-pull-requests-limit: 10

.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+"on":
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    name: Lint (Biome)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/ci-setup
+      - name: Run Turbo lint
+        env:
+          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            pnpm -s turbo run lint --filter=...[origin/${{ github.base_ref }}]
+          else
+            pnpm -s turbo run lint
+          fi
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/ci-setup
+      - name: Run Turbo typecheck
+        env:
+          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            pnpm -s turbo run typecheck --filter=...[origin/${{ github.base_ref }}]
+          else
+            pnpm -s turbo run typecheck
+          fi
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/ci-setup
+      - name: Run Turbo test
+        env:
+          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            pnpm -s turbo run test --filter=...[origin/${{ github.base_ref }}]
+          else
+            pnpm -s turbo run test
+          fi
+  build:
+    name: Build
+    needs: ["lint", "typecheck"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/ci-setup
+      - name: Run Turbo build + codex:gen:check
+        env:
+          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            pnpm -s turbo run build codex:gen:check \
+              --filter=...[origin/${{ github.base_ref }}]
+          else
+            pnpm -s turbo run build codex:gen:check
+          fi

.github/workflows/codeql.yml

@@ -0,0 +1,42 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  schedule:
+    - cron: '30 1 * * 0'
+
+jobs:
+  analyze:
+    name: CodeQL analysis
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ['javascript-typescript']
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        queries: security-extended
+        config-file: ./.github/codeql/codeql-config.yml
+
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v3
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

.github/workflows/scorecard.yml

@@ -0,0 +1,68 @@
+name: Scorecard supply-chain security
+"on":
+  # For Branch-Protection check. Only the default branch is supported. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
+  branch_protection_rule:
+  # To guarantee Maintained check is occasionally updated. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
+  schedule:
+    - cron: '20 7 * * 2'
+  push:
+    branches: ["main"]
+
+# Declare default permissions as read only.
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed to upload the results to code-scanning dashboard.
+      security-events: write
+      # Needed to publish results and get a badge (see publish_results below).
+      id-token: write
+      # Needed for checkout.
+      contents: read
+      actions: read
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@v2.4.0
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
+          # - you want to enable the Branch-Protection check on a *public* repository.
+          # - you are installing Scorecards on a *private* repository.
+          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat.
+          # repo_token: ${{ secrets.SCORECARD_TOKEN }}
+
+          # Public repositories:
+          #   - Publish results to OpenSSF REST API for easy access by consumers
+          #   - Allows the repository to include the Scorecard badge.
+          #   - See https://github.com/ossf/scorecard-action#publishing-results.
+          # For private repositories:
+          #   - `publish_results` will always be set to `false`, regardless
+          #     of the value entered here.
+          publish_results: true
+
+      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
+      # format to the repository Actions tab.
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@v4
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard.
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif

.gitignore

@@ -19,12 +19,13 @@ pnpm-debug.log*
 .env.*
 !.env.example
 
-# Bun
-.bun/
-bun.lockb
-
 # Local Codex workspace data
 .codex/
+docs/research/
+
+# Generated Codex JSON schema bundles (reproducible artifacts)
+tools/codex-schemas/
+tools/.trash/
 
 # Tooling caches
 .eslintcache
@@ -44,4 +45,5 @@ opensrc/
 .claude/
 .cursor/
 .agent/
-
+.agents/
+.firecrawl/

.nvmrc

@@ -0,0 +1 @@
+24.11