# Project SDE Meeting Toolkit ## Purpose This folder holds two workshop tools for Project SDE. Each tool is one HTML file. Each tool runs in a web browser. The tools do not need a server or a database. The tools do not connect to the Work Package Suite application. ## Contents | File | Purpose | |---|---| | `tools/field-problem-workshop.html` | Field problem workshop. Captures problems, groups them into clusters, and records breadcrumbs and actions. | | `tools/scope-lock-meeting-suite.html` | Scope lock meeting suite. Holds the scope boundary board, the MVP priority ranker, the decision registry, and the Micron pilot readiness check. | | `skills/construction-breadcrumbs.skill` | A Claude skill. The skill encodes the breadcrumb method. Install this skill to use the method in any Claude chat. | ## Requirements Install Node.js version 18 or later to run the local server. You do not need Node.js to open a tool file directly in a browser. ## Setup Follow these steps to set up the project on your computer. 1. Open a terminal. 2. Go to the `sde-meeting-toolkit` folder. 3. Run this command to check that Git tracks the folder: ``` git status ``` 4. To use the AI draft button through the local server, copy `.env.example` to `.env`. 5. Open `.env` and set `ANTHROPIC_API_KEY` to your key. 6. Do not commit `.env`. Git already ignores it. Skip steps 4 through 6 if you plan to run the AI draft button only from inside a Claude artifact (see Method 3 below). The project has no other dependencies to install. ## Run a tool Choose one of the two methods below. ### Method 1: Open the file directly 1. Open a file browser. 2. Go to the `tools` folder. 3. Double-click a tool file to open it in your default browser. This method works offline. This method does not run the AI draft button in the Field Problem Workshop. ### Method 2: Run a local server Use this method to test the tools the way a browser would load them from a web server. This method also makes the AI draft button work, if you completed steps 4 through 6 in Setup. 1. Open a terminal. 2. Go to the `sde-meeting-toolkit` folder. 3. Run this command: ``` npm run serve ``` 4. Check the terminal output. It reports whether it found an API key. 5. Open a browser. 6. Go to this address: `http://localhost:5173` 7. Click a tool link, or go directly to a file under the `tools` folder. 8. Press `Ctrl+C` in the terminal to stop the server. ### Method 3: Use the tool as a Claude artifact Use this method to run the AI draft button without setting up a local API key. 1. Open a chat in Claude. 2. Upload the tool file, or add it to a Claude project. 3. Ask Claude to render the file as an artifact. This method needs a network connection. It does not need the local server or a `.env` file. ## AI draft button The Field Problem Workshop calls Claude to draft breadcrumb fields. It reaches Claude through one of two paths, never directly from the browser to the Anthropic API. - **Local server path**: The browser calls `/api/claude` on your own machine. `server.js` reads `ANTHROPIC_API_KEY` from `.env` and forwards the request. Your key stays on your machine and is never sent to the browser. - **Claude artifact path**: The Claude environment handles the request. No key setup is needed on your side. If you run a tool by double-clicking the file, with no server, the AI draft button fails. This is expected: a plain file has no server to call. If you run `npm run serve` without a `.env` file, or with `ANTHROPIC_API_KEY` unset, the button reports that the key is missing. Add the key to `.env` and restart the server to fix it. ## Save and load your work The two tools store data in different ways. **Field Problem Workshop**: The tool holds data in the browser session only. Closing the browser tab erases unsaved data. 1. Click Export JSON before you close the tool. 2. Save the JSON file to your computer. 3. Click Load JSON the next time you open the tool. 4. Select the saved JSON file to restore your data. **Scope Lock Meeting Suite**: The tool saves data automatically to the browser's local storage on the computer where you open it. Local storage does not transfer to another computer. 1. Click Export in the tool to create a durable record. 2. Save the exported file to your computer or to a shared drive. ## Reset a tool Each tool has a Reset control. - Field Problem Workshop: Reset returns the tool to the July 21 baseline. The baseline holds 43 problems in 7 root clusters, 6 breadcrumbs, and 5 actions. - Scope Lock Meeting Suite: Reset returns the tool to its starting state. Reset erases current data in the tool. Export your data before you click Reset. ## Install the skill 1. Open Claude. 2. Open the skill file: `skills/construction-breadcrumbs.skill`. 3. Use the Save skill action to install it. 4. Open a new chat to use the skill. ## Version control This folder is a Git repository. Use normal Git commands to track changes. ``` git add . git commit -m "Describe your change here" ``` The `.gitignore` file excludes `node_modules` and common system files from commits. ## Deploy for the whole company Use this when the tool needs to be reachable by anyone on the internal network or VPN, not just on one person's machine. This uses a company-owned Anthropic API key shared by everyone who reaches the tool, so it adds a per-person login, a per-person daily token quota, and a request cap that a solo local setup does not need. 1. Get an Anthropic API key billed to a company account, not a personal one. IT or finance should provision this, since it is billed like any other company vendor cost. 2. Decide who needs their own login. Each name gets its own password and its own daily token quota, tracked separately. 3. On the host or container platform, set these values as environment variables, or in a `.env` file next to `docker-compose.yml`: ``` ANTHROPIC_API_KEY= APP_USERS=alice:pass1,bob:pass2,carol:pass3 TOKEN_LIMIT_PER_USER=50000 ``` 4. Build and run the container: ``` docker compose up -d --build ``` 5. To run this alongside the existing Work Package Suite container instead of on its own, copy the `sde-meeting-toolkit` service block from `docker-compose.yml` into that stack's compose file, including its `volumes` entry, and apply the same environment variables there. 6. Confirm the login prompt appears when you open the tool's URL from another machine on the network, and that it accepts one of the named user/password pairs. ### What the login gate does and does not do - It requires a username and password before any page or API call on this tool succeeds, and identifies which named user made each AI draft call. - It does not encrypt traffic on its own. Run this behind the same network and VPN protections used for the Work Package Suite, and add TLS at the reverse proxy or load balancer if one is already in place for that stack. - It is a shared-credential list, not a real identity system. Anyone who has a name's password can use that name's quota. If real single-sign-on attribution matters later, that needs a larger integration than this tool currently supports. - Old single-shared-login setups still work: set `APP_USERNAME` and `APP_PASSWORD` instead of `APP_USERS` if you want everyone to share one login and one quota, unchanged from before this feature existed. ### Per-user token quota `TOKEN_LIMIT_PER_USER` caps combined input and output tokens per named user, per UTC calendar day. Default: 50000 tokens/day, which is roughly 100 to 200 AI drafts with this tool's prompt size. A user who hits the cap gets a clear error naming their usage and the time until reset, instead of a silent failure or an unexplained cost. Usage is written to `TOKEN_USAGE_FILE` (default `./data/token-usage.json`) after every AI call. In Docker, `docker-compose.yml` mounts `./data` as a volume so this file survives a restart or redeploy. If you remove that volume mount, usage resets to zero every time the container restarts, which defeats the point of a daily cap. To reset one person's quota early, stop the container, edit their entry out of the usage file (or set its `date` to any past date), and restart. To raise or lower the cap for everyone, change `TOKEN_LIMIT_PER_USER` and restart; the change applies from that point on, not retroactively. ### Rate limit `RATE_LIMIT_MAX` and `RATE_LIMIT_WINDOW_MS` cap AI draft requests per source IP address, independent of the token quota. This catches a runaway script in the first few seconds, before it could burn through a whole day's token quota. Defaults: 20 requests per 5 minutes. ## Relation to the Work Package Suite These tools support meetings about the Work Package Suite project. The tools do not call the Work Package Suite application. The tools do not read or write Work Package Suite data. Treat this toolkit and the Work Package Suite codebase as separate projects.