Upgrades from your work

.claude/launch.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "plex-api",
+      "runtimeExecutable": "py",
+      "runtimeArgs": ["run_dev.py"],
+      "port": 5000
+    },
+    {
+      "name": "web",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["--prefix", "web", "vite", "web", "--port", "5174"],
+      "port": 5174
+    }
+  ]
+}

.env.example

@@ -0,0 +1,45 @@
+# .env.example
+#
+# Copy this file to .env.local (which is gitignored) and fill in real values.
+# bootstrap.py loads .env.local at startup so you don't have to set these
+# variables in every shell. Real shell environment variables always win
+# over .env.local via setdefault semantics.
+#
+# Get your Consumer Key and Consumer Secret from:
+#   https://developers.plex.com/  →  My Apps  →  Fusion2Plex  →  Key
+
+# ── REQUIRED ────────────────────────────────────────────────────────
+PLEX_API_KEY=your-consumer-key-here
+PLEX_API_SECRET=your-consumer-secret-here
+
+# ── OPTIONAL ────────────────────────────────────────────────────────
+# Override the target tenant. Defaults to the verified Grace Engineering
+# production tenant. Set this only if you need to point at a different
+# tenant for testing.
+# PLEX_TENANT_ID=58f781ba-1691-4f32-b1db-381cdb21300c
+
+# Hit the test environment (test.connect.plex.com) instead of production
+# (connect.plex.com). The Fusion2Plex app currently only exists in
+# production, so leaving this unset is correct for normal use.
+# PLEX_USE_TEST=1
+
+# Allow mutating HTTP methods (POST/PUT/PATCH/DELETE) against production.
+# OFF by default — every write to connect.plex.com affects real Grace
+# manufacturing data. Set to 1 only when you intentionally want to write,
+# and unset it as soon as you're done.
+# PLEX_ALLOW_WRITES=1
+
+# ── SUPABASE — Datum ingest layer (issue #31) ──────────────────────
+# Dedicated `datum` project. Service role key bypasses RLS and is
+# used by sync_supabase.py to populate the libraries, tools, and
+# cutting_presets tables. NEVER ship the service role key to a browser.
+SUPABASE_URL=https://<your-datum-project-ref>.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-jwt-here
+
+# ── AUTODESK PLATFORM SERVICES (APS) — cloud tool libraries ──────
+# Register an app at https://aps.autodesk.com → Applications → Create.
+# App type: "Traditional Web App". Enable API: Data Management.
+# Required scopes: data:read
+APS_CLIENT_ID=your-aps-client-id-here
+APS_CLIENT_SECRET=your-aps-client-secret-here
+# APS_CALLBACK_URL=http://localhost:5000/api/aps/callback

.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: tests
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+
+jobs:
+  test:
+    name: pytest
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            requirements-dev.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+
+      - name: Run pytest
+        run: pytest

.gitignore

@@ -0,0 +1,47 @@
+__pycache__/
+*.pyc
+
+# dotenv — local secrets, NEVER commit
+.env
+.env.local
+.env.*.local
+
+# APS OAuth tokens — local-only, contains access/refresh tokens
+.aps_tokens.json
+
+# Node / frontend
+node_modules/
+
+# editor / IDE
+.vscode/
+.idea/
+*.swp
+
+# Python tooling
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+*.egg-info/
+build/
+dist/
+
+# Large reference material (kept locally, not in git)
+data/
+
+# Runtime outputs (regenerated by extractors, not source of truth)
+outputs/
+
+# Claude Code worktree scratch space
+.claude/worktrees/
+
+# Ad-hoc probe scripts, one-off dumps, and similar throwaway work
+scratch/
+
+# Claude Code per-machine permissions cache (regenerated on demand)
+.claude/settings.local.json
+
+# Plex mock — ephemeral capture data (POSTs the sync sent against the mock)
+tools/plex_mock/captures/
+tools/plex_mock/*.db
+tools/plex_mock/*.db-journal

CLAUDE.md

@@ -0,0 +1,94 @@
+# Claude memory file
+
+This is the entry point for Claude Code (or any AI agent) working on this
+repository. **Read these files in this order before doing anything**:
+
+1. **[`docs/BRIEFING.md`](./docs/BRIEFING.md)** — primary context document. Project
+   purpose, current credentials, current Plex environment, verified
+   endpoint matrix, gotchas, immediate TODO, "History of incorrect
+   hypotheses" postmortem, and a session log of what's been done. **This
+   is the most important file in the repo for AI context.**
+
+2. **[`docs/Plex_API_Reference.md`](./docs/Plex_API_Reference.md)** — verified URL
+   patterns, the 401-vs-404 reading guide, and the no-pagination gotcha.
+   Read this before writing any new Plex API call.
+
+3. **[`docs/Fusion360_Tool_Library_Reference.md`](./docs/Fusion360_Tool_Library_Reference.md)**
+   — Fusion JSON schema and field-to-Plex mapping. Read this before
+   writing anything that consumes the local Fusion library files.
+
+4. **[`docs/Postman_Collections.md`](./docs/Postman_Collections.md)** —
+   the two Postman collections (Plex API — Datum and Fusion 360 Tool
+   Libraries — Datum), including the full endpoint catalog with
+   verified-vs-probe status, the `[NS]` naming convention, the safe
+   write workflow, and how to add new requests via the Postman MCP.
+   Read this before touching the collections or before exploring a new
+   Plex namespace from the Postman UI.
+
+5. **[`TODO.md`](./TODO.md)** — project roadmap, links to GitHub Issues
+   for live status.
+
+6. **Datum Notion page** — https://www.notion.so/Grace-Engineering-Fusion2Plex-33c3160a3abf81f1aac0e58101952be5
+   — **read at the start of every session.** Current State block tells
+   you phase, next action, and test count. End each session by updating
+   that block + appending one line to the Decision Log. See the
+   "Notion pages" section in `docs/BRIEFING.md` for details.
+
+7. **Supabase staging layer** — Fusion JSON is ingested into the
+   `libraries`, `tools`, and `cutting_presets` tables in the dedicated
+   `datum` Supabase project (us-east-2) before anything pushes to Plex.
+   Schema spec: [Notion · Supabase Schema Design](https://www.notion.so/33c3160a3abf814c885cc174cda76d17).
+   Code: `supabase_client.py`, `sync_supabase.py`, `scripts/load_sample.py`.
+   Credentials: `SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY` in `.env.local`.
+   Issue #31. Downstream (`build_supply_item_payload`, #3) reads from
+   the `tools` table, not raw JSON.
+
+## Hard rules
+
+- **Never read credentials from images.** Always have the user paste them
+  as text or via Insomnia "Generate Code" output. We learned this the
+  hard way (see BRIEFING.md "History of incorrect hypotheses §1").
+- **Never hardcode credentials.** They live in `.env.local` (gitignored),
+  loaded by `bootstrap.py`. Production deploy uses real shell env vars.
+- **Never bypass the production write guard.** Mutating HTTP methods on
+  `connect.plex.com` are refused at `/api/plex/raw` unless
+  `PLEX_ALLOW_WRITES=1` is explicitly set in the environment.
+- **Always run `pytest` before committing.** Branch protection on master
+  requires the `pytest` GitHub Actions check to pass before any merge.
+- **Use the `claude/<short-name>` branch naming convention** for new
+  branches off master, then auto-merge with `gh pr merge --auto --squash`.
+- **Never ship the Supabase service role key to a browser.** It bypasses
+  RLS. Server-side ingest scripts only.
+
+## Quick commands
+
+```powershell
+# Run the local endpoint tester (overrides shell env from .env.local)
+py run_dev.py
+
+# Run tests
+py -m pytest
+
+# Open a PR with auto-merge
+gh pr create --base master --head claude/my-branch --title "..." --body "..."
+gh pr merge <number> --auto --squash
+```
+
+## Things this repo does NOT have
+
+- A test environment for the Datum Plex app — production is the
+  only environment we have credentials for. Be cautious.
+- A CI badge or release versioning yet
+- Any tooling-API endpoints — Plex's tool data lives under
+  `inventory/v1/inventory-definitions/supply-items`, NOT
+  `tooling/v1/*` or `mdm/v1/parts`. See BRIEFING.md.
+
+## When in doubt
+
+- The repo is small and the context fits in one read of BRIEFING.md +
+  Plex_API_Reference.md. Read them; don't guess.
+- Claude Code has a built-in `tenant_whoami` diagnostic at
+  `/api/diagnostics/tenant` — run that first whenever the connection
+  state is unclear.
+- Open a PR. CI is fast (~10s) and branch protection guarantees you
+  can't break master.