Modernize ClearPath for safer, maintainable clinical drafting

.env.example

@@ -0,0 +1,5 @@
+# Required: create a key at https://platform.claude.com/settings/keys
+ANTHROPIC_API_KEY=your_anthropic_api_key
+
+# Optional: pin a different compatible Claude model.
+ANTHROPIC_MODEL=claude-sonnet-5

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type-check
+        run: npm run typecheck
+
+      - name: Test
+        run: npm test
+
+      - name: Build
+        run: npm run build

.gitignore

@@ -32,9 +32,9 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
 
 # vercel
-.vercel
 
 # typescript
 *.tsbuildinfo

CLAUDE.md

@@ -15,16 +15,17 @@ ClearPath SUD is a web-based tool for substance use disorder (SUD) professionals
 ## Domain Context
 
 - **ASAM** (American Society of Addiction Medicine) defines a multidimensional assessment framework with 6 dimensions used for SUD treatment planning
+- The ASAM Mapper targets the adult **Fourth Edition** dimensions; readiness to change is integrated across dimensions rather than treated as a standalone dimension
 - **SUDP** = Substance Use Disorder Professional
-- Clinical documentation must align with ASAM criteria for insurance reimbursement and regulatory compliance
+- Clinical documentation requirements vary by payer and jurisdiction; ASAM alignment may be one relevant requirement but does not itself guarantee compliance
 - The target users are trainees and early-career clinicians who need guidance writing assessments, not experienced supervisors
 - Think "Goblin Tools for SUD documentation" — simple, focused utilities, not an EHR replacement
 
 ## Tech Stack
 
 - **Next.js 16** (App Router, TypeScript, `src/` directory)
 - **Tailwind CSS v4** — clinical palette (blues/whites/slates)
-- **Anthropic SDK** (`@anthropic-ai/sdk`) — Claude Sonnet for AI generation
+- **Anthropic SDK** (`@anthropic-ai/sdk`) — Claude Sonnet 5 by default, configurable with `ANTHROPIC_MODEL`
 - **Streaming responses** — text appears progressively
 
 ## Development
@@ -36,7 +37,7 @@ npm run start    # Run production build
 npm run lint     # Run ESLint
 ```
 
-Requires `ANTHROPIC_API_KEY` in `.env.local`.
+Requires `ANTHROPIC_API_KEY` in `.env.local`. Copy `.env.example` to get started.
 
 ## Project Structure
 
@@ -50,23 +51,33 @@ src/
 │   ├── doc-reviewer/           # Tool 3: Documentation Reviewer
 │   └── api/                    # Streaming API routes for each tool
 ├── components/                 # Shared UI components
+├── hooks/                      # Shared client-side streaming behavior
 │   ├── nav.tsx                 # Top navigation
 │   ├── tool-card.tsx           # Home page cards
 │   ├── text-input.tsx          # Textarea with char count
 │   ├── submit-button.tsx       # Button with loading spinner
 │   ├── result-display.tsx      # Streaming output + copy button
 │   └── dimension-badge.tsx     # ASAM dimension status badges
 └── lib/
-    ├── anthropic.ts            # Anthropic client singleton
-    └── prompts.ts              # System prompts for all 3 tools
+    ├── anthropic.ts            # Lazy server-only Anthropic client
+    ├── prompts.ts              # System prompts for all 3 tools
+    ├── streaming-tool-route.ts # Shared validation and streaming response
+    └── tool-input.ts           # Shared input limits and validation
 ```
 
 ## Architecture
 
-- **No database.** Text goes to Claude API and back; nothing persists.
+- **No application database.** Text is processed by the server and Anthropic API; hosting/provider logs and retention settings still matter.
 - **No auth.** MVP is open; auth comes later.
-- **Each tool is self-contained.** Page owns its own state (input, result, isLoading).
-- **All API routes follow the same pattern:** validate → call Claude with system prompt → stream back.
+- **Each page is thin.** It owns the input text while the shared streaming hook owns result, error, loading, and cancellation state.
+- **Shared request path:** thin API adapters call one validator/streaming helper; pages use one client streaming hook.
+
+## Safety boundaries
+
+- Treat the project as an educational prototype, not clinical decision support.
+- Do not add claims that it diagnoses, assigns ASAM risk ratings, recommends level of care, or guarantees compliance.
+- Keep the visible de-identification and clinician-review warnings intact.
+- Clinical prompt changes should be checked against current primary sources and reviewed by qualified clinicians before real-world use.
 
 ## Status
 

README.md

@@ -0,0 +1,202 @@
+# ClearPath SUD
+
+ClearPath is a focused set of AI-assisted drafting tools for substance use disorder (SUD) professionals. It helps clinicians and trainees organize treatment-plan language, check whether an assessment addresses the six dimensions in *The ASAM Criteria, Fourth Edition*, and review clinical documentation before submission.
+
+> [!IMPORTANT]
+> ClearPath is an educational prototype, not a clinical decision-support system or an electronic health record. It does not diagnose, assign ASAM risk ratings, determine level of care, replace qualified supervision, or guarantee clinical, payer, legal, or regulatory compliance. Do not enter identifiable patient information into an unapproved deployment.
+
+## What it does
+
+| Tool | Input | Output |
+| --- | --- | --- |
+| Treatment Plan Helper | De-identified client statements and clinical observations | A problem statement, long-term goal, SMART objectives, interventions, and clinical rationale |
+| ASAM Mapper | A de-identified assessment narrative | A documentation-coverage review for all six Fourth Edition dimensions, including evidence and suggested follow-up areas |
+| Documentation Reviewer | A de-identified progress note, assessment, or treatment-plan update | Supervisor-style feedback on strengths, clarity, person-first language, completeness, and revision priorities |
+
+Responses stream into the browser as they are generated. The application itself has no database, user accounts, or persistence layer.
+
+## Clinical framework
+
+The ASAM Mapper follows the adult assessment dimensions in *The ASAM Criteria, Fourth Edition*:
+
+1. Intoxication, Withdrawal, and Addiction Medications
+2. Biomedical Conditions
+3. Psychiatric and Cognitive Conditions
+4. Substance Use-Related Risks
+5. Recovery Environment Interactions
+6. Person-Centered Considerations
+
+Readiness and motivation are considered across the Fourth Edition dimensions and during treatment planning; they are not represented as a standalone dimension. See ASAM's [Fourth Edition overview](https://www.asam.org/asam-criteria/asam-criteria-4th-edition) and [official assessment guides](https://www.asam.org/asam-criteria/implementation-tools/Criteria-assessment-guides) for authoritative guidance.
+
+ClearPath is not affiliated with, endorsed by, or certified by the American Society of Addiction Medicine. “ASAM” and “The ASAM Criteria” are the property of their respective owner. This repository implements a documentation aid and does not reproduce the proprietary admission criteria or replace the official materials and training.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[Browser] -->|de-identified text| B[Next.js API route]
+    B --> C[Shared validation]
+    C -->|50–5,000 characters| D[Anthropic Messages API]
+    D -->|text stream| B
+    B -->|no-store response| A
+```
+
+Each tool has its own system prompt and token budget, but the server-side request handling is shared. Requests are validated again on the server, sent to the configured Claude model, and returned as plain-text streams. Navigating away or pressing **Stop** aborts the browser request.
+
+## Tech stack
+
+- [Next.js](https://nextjs.org/) App Router with TypeScript
+- React
+- Tailwind CSS
+- [Anthropic TypeScript SDK](https://github.com/anthropics/anthropic-sdk-typescript)
+- Vitest for unit tests
+- GitHub Actions for lint, type, test, and build verification
+
+The default model is `claude-sonnet-5`; set `ANTHROPIC_MODEL` to pin another compatible Claude API model without changing code.
+
+## Quick start
+
+### Prerequisites
+
+- Node.js 20.9 or newer (Node.js 22 LTS is used in CI)
+- npm
+- An [Anthropic API key](https://platform.claude.com/settings/keys)
+
+### Install and run
+
+```bash
+git clone https://github.com/rdsciv/ClearPath.git
+cd ClearPath
+npm ci
+cp .env.example .env.local
+```
+
+Set your key in `.env.local`:
+
+```dotenv
+ANTHROPIC_API_KEY=your_anthropic_api_key
+ANTHROPIC_MODEL=claude-sonnet-5
+```
+
+Then start the development server:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## Environment variables
+
+| Variable | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `ANTHROPIC_API_KEY` | Yes | — | Authenticates server-side requests to the Anthropic API |
+| `ANTHROPIC_MODEL` | No | `claude-sonnet-5` | Selects a compatible model for all three tools |
+
+Environment files are ignored by Git, except for the safe `.env.example` template. Never commit a real API key or expose it through a `NEXT_PUBLIC_` variable.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `npm run dev` | Start the local development server |
+| `npm run lint` | Run ESLint |
+| `npm run typecheck` | Run the TypeScript compiler without emitting files |
+| `npm test` | Run unit tests once |
+| `npm run build` | Create a production build |
+| `npm run start` | Serve a production build |
+| `npm run check` | Run lint, type-check, tests, and build in sequence |
+
+## Project structure
+
+```text
+ClearPath/
+├── .github/workflows/ci.yml       # Pull-request and master-branch checks
+├── src/
+│   ├── app/
+│   │   ├── api/                   # Thin route adapters for each AI tool
+│   │   ├── asam-mapper/           # ASAM documentation-coverage UI
+│   │   ├── doc-reviewer/          # Documentation feedback UI
+│   │   └── treatment-plan/        # Treatment-plan drafting UI
+│   ├── components/                # Navigation, inputs, notices, and results
+│   ├── hooks/
+│   │   └── use-streaming-tool.ts  # Shared browser streaming and cancellation
+│   └── lib/
+│       ├── anthropic.ts           # Lazy server-only Anthropic client
+│       ├── asam.ts                # Fourth Edition labels and status parser
+│       ├── prompts.ts             # Tool-specific system prompts
+│       ├── streaming-tool-route.ts # Shared API validation and streaming
+│       └── tool-input.ts           # Shared input limits and validation
+└── tests/                         # Pure-function unit tests
+```
+
+## API behavior
+
+All three endpoints accept the same JSON shape:
+
+```json
+{
+  "input": "De-identified clinical narrative of at least 50 characters"
+}
+```
+
+Endpoints:
+
+- `POST /api/treatment-plan`
+- `POST /api/asam-mapper`
+- `POST /api/doc-reviewer`
+
+Input is trimmed and must contain 50–5,000 characters. Successful responses use `text/plain; charset=utf-8` and stream incrementally. Validation errors return `400`; a missing API key returns `503`; failures that occur before streaming begins return `502`. API responses include `Cache-Control: no-store`.
+
+## Privacy, security, and responsible use
+
+ClearPath intentionally stores no submissions in an application database. A submission is still processed by the deployed Next.js server and sent to Anthropic, so “no persistence” is not the same as “no disclosure.” Data handling also depends on hosting logs, observability tools, network infrastructure, the Anthropic account's settings, and any agreements in place.
+
+Before any real clinical use:
+
+- Establish an approved de-identification workflow and train users not to paste protected health information (PHI).
+- Complete organizational privacy, security, legal, clinical-safety, and vendor reviews.
+- Confirm whether HIPAA or other laws apply and put required agreements—including a BAA where applicable—in place with every relevant vendor.
+- Review Anthropic's current [privacy and data-handling documentation](https://privacy.anthropic.com/) for the account and API configuration being used.
+- Add authentication, authorization, rate limiting, abuse controls, audit strategy, monitoring, and a retention/logging policy.
+- Keep secrets server-side and rotate them if exposure is suspected.
+- Validate prompts and outputs with qualified clinicians before deployment, and revalidate them whenever the model or clinical standard changes.
+
+The included headers, input bounds, de-identification warning, and non-persistence architecture are useful safeguards, but they do not make a deployment compliant or clinically validated.
+
+## Known limitations
+
+- AI output can be incomplete, inaccurate, or overly confident and must be reviewed by a qualified person.
+- The app does not assign ASAM risk ratings or recommend a level of care.
+- There is no authentication, tenant isolation, rate limiting, usage metering, audit log, database, or EHR integration.
+- Output is rendered as plain text, so Markdown markers from the model remain visible.
+- The ASAM status badges depend on the model following the requested section and status format.
+- There are no browser-level or live Anthropic integration tests; unit tests cover input validation and status parsing.
+- Payer and jurisdictional documentation requirements vary and are not encoded as authoritative rules.
+
+## Deployment
+
+The project can run on any Node.js platform that supports Next.js server routes and streaming responses. Configure `ANTHROPIC_API_KEY` as a server-side secret and, optionally, `ANTHROPIC_MODEL` in the deployment environment.
+
+Do not treat a successful technical deployment as approval for clinical data. Complete the privacy and production-readiness work above before enabling real users.
+
+## Contributing
+
+1. Create a branch from `master`.
+2. Keep clinical claims grounded in current primary sources and flag any change to prompt behavior.
+3. Add or update tests for parser and validation changes.
+4. Run `npm run check`.
+5. Open a pull request describing user impact, safety implications, and validation performed.
+
+## Roadmap ideas
+
+- Structured model output with schema validation instead of Markdown parsing
+- Authentication, rate limits, and per-user usage controls
+- Configurable prompt/model versions with evaluation fixtures
+- Clinician-reviewed quality and safety evaluation suite
+- Accessible rendered Markdown with export options
+- Optional, explicitly governed EHR workflows
+
+## License
+
+No open-source license is currently included. Unless a license is added, default copyright restrictions apply.

next.config.ts

@@ -1,7 +1,26 @@
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
-  /* config options here */
+  poweredByHeader: false,
+  async headers() {
+    return [
+      {
+        source: "/(.*)",
+        headers: [
+          { key: "X-Content-Type-Options", value: "nosniff" },
+          { key: "X-Frame-Options", value: "DENY" },
+          {
+            key: "Referrer-Policy",
+            value: "strict-origin-when-cross-origin",
+          },
+          {
+            key: "Permissions-Policy",
+            value: "camera=(), microphone=(), geolocation=()",
+          },
+        ],
+      },
+    ];
+  },
 };
 
 export default nextConfig;