docs: integrate npm package documentation

docs/docs-npm/api/adapters.mdx

@@ -0,0 +1,64 @@
+---
+title: Adapters
+description: ILanguageAdapter — pluggable analysis, transforms, and verification.
+---
+
+## Interface
+
+Language adapters implement `ILanguageAdapter` (`src/adapters/interface.ts`):
+
+```typescript
+interface ILanguageAdapter {
+  readonly name: string;
+  readonly extensions: string[];
+  readonly displayName: string;
+
+  detect(projectRoot: string): Promise<boolean>;
+
+  analyze(files: string[]): Promise<CodeIssue[]>;
+
+  transform(file: string, code: string, issue: CodeIssue): Promise<TransformResult>;
+
+  verifySyntax(path: string, code: string): Promise<CheckResult>;
+  verifyImports(path: string, code: string): Promise<CheckResult>;
+  verifyTests(path: string, code: string): Promise<CheckResult>;
+
+  generateDiff(original: string, transformed: string): string;
+
+  buildImportGraph(projectRoot: string): Promise<ImportGraph>;
+  buildCallGraph(files: string[]): Promise<CallGraph>;
+}
+```
+
+**Contract:** `analyze` must return issues with **blast radius** populated for every item.
+
+---
+
+## Graphs
+
+- **ImportGraph** — `dependentsOf`, `dependenciesOf`, `allFiles` for blast radius fan-in.
+- **CallGraph** — `transitiveCallersOf`, `allPublicFunctionsIn` for function-level impact.
+
+---
+
+## Built-in adapters
+
+| Adapter | Module | Notes |
+|---------|--------|------|
+| Python | `PythonAdapter` | Full analyzer suite |
+| TypeScript | `TypeScriptAdapter` | Graphs + verification; static analysis coverage varies by version |
+
+`AdapterRegistry` discovers adapters and scores them against the project.
+
+---
+
+## Transforms
+
+`transform` returns `TransformResult` with `transformedCode`, human-readable `description`, and a coarse `riskLevel`. The **autofix engine** chooses fixers by issue; verification runs **after** transform.
+
+---
+
+## See also
+
+- [Languages](/docs-npm/languages/python)
+- [Orchestrator](/docs-npm/api/orchestrator)

docs/docs-npm/api/models.mdx

@@ -0,0 +1,110 @@
+---
+title: Models
+description: Core types for issues, blast radius, verification, and analysis results.
+---
+
+## Severity and blast levels
+
+```typescript
+type Severity = 'critical' | 'high' | 'medium' | 'low';
+type BlastLevel = 'trivial' | 'low' | 'medium' | 'high' | 'critical';
+```
+
+---
+
+## BlastRadius
+
+Every `CodeIssue` carries a non-optional `BlastRadius`:
+
+```typescript
+interface BlastRadius {
+  affectedFiles: string[];
+  affectedFunctions: string[];
+  affectedTestFiles: string[];
+  score: number; // 0–100
+  level: BlastLevel;
+}
+```
+
+---
+
+## TemporalProfile
+
+Optional enrichment when Git history is available:
+
+```typescript
+interface TemporalProfile {
+  lastModified: Date;
+  changeVelocity: number;
+  coChangePairs: string[];
+  daysSinceLastTouch: number;
+}
+```
+
+---
+
+## CodeIssue
+
+```typescript
+interface CodeIssue {
+  id: string;
+  file: string;
+  line: number;
+  column?: number;
+  severity: Severity;
+  type: string;
+  message: string;
+  suggestion?: string;
+  fixable: boolean;
+  fixerName?: string;
+  blastRadius: BlastRadius;
+  temporal?: TemporalProfile;
+  ruleId: string;
+}
+```
+
+---
+
+## VerificationResult
+
+```typescript
+interface VerificationResult {
+  safeToApply: boolean;
+  passed: boolean;
+  checksRun: string[];
+  checksPassed: string[];
+  checksFailed: string[];
+  blockingReason?: string;
+  confidenceScore: number;
+  verificationMs: number;
+  skippedChecks: string[];
+}
+```
+
+---
+
+## AnalysisResult
+
+```typescript
+interface AnalysisResult {
+  target: string;
+  filesAnalyzed: number;
+  filesSkipped: number;
+  issues: CodeIssue[];
+  languageBreakdown: Record<string, number>;
+  durationMs: number;
+  timestamp: Date;
+}
+```
+
+---
+
+## Pipeline / fix queue
+
+The orchestrator uses `PipelineSession`, `FixQueueItem`, `FixStatus`, and related types for fix application and blocking. See `src/core/models.ts` for full definitions.
+
+---
+
+## Source
+
+Definitions live in `src/core/models.ts` in the repository.

docs/docs-npm/api/orchestrator.mdx

@@ -0,0 +1,64 @@
+---
+title: Orchestrator
+description: High-level analyze and autofix pipeline.
+---
+
+## Class
+
+```typescript
+class Orchestrator {
+  constructor(
+    adapter: ILanguageAdapter,
+    config: RefactronConfig,
+    projectRoot: string,
+  );
+
+  analyze(target: string): Promise<OrchestratorResult>;
+
+  autofix(
+    target: string,
+    options?: { dryRun?: boolean; verify?: boolean },
+  ): Promise<{ session: PipelineSession; analysis: AnalysisResult }>;
+
+  autofixFromAnalysis(
+    analysis: AnalysisResult,
+    options?: { dryRun?: boolean; verify?: boolean },
+  ): Promise<PipelineSession>;
+}
+```
+
+`OrchestratorResult` bundles a `PipelineSession` with the `AnalysisResult` from **`analyze`**.
+
+---
+
+## analyze
+
+Runs the **AnalysisEngine** on the target path, records issue counts on an internal pipeline session, persists via **SessionStore**, and returns both session summary and full **AnalysisResult**.
+
+---
+
+## autofix
+
+1. Calls **`analyze`** on the same target.
+2. Enqueues fixable issues, runs **AutoFixEngine** transforms.
+3. If verification is required (CLI flag or `config.autofix.require_verification`), runs **VerificationEngine** before each write.
+4. On success, **BackupManager** + **atomicWrite** persist changes.
+
+---
+
+## autofixFromAnalysis
+
+Skips a new scan — used by the REPL **`autofix`** command when reconstructing analysis from a **WorkSession** so fixes apply to the stored issue list without re-running analyzers.
+
+---
+
+## Source
+
+`src/core/orchestrator.ts`
+
+---
+
+## See also
+
+- [Models](/docs-npm/api/models)
+- [Verification](/docs-npm/concepts/verification)

docs/docs-npm/api/overview.mdx

@@ -0,0 +1,33 @@
+---
+title: API overview
+description: Programmatic building blocks in the Refactron TypeScript codebase.
+---
+
+## Package layout
+
+The published **npm** package is primarily the **`refactron`** CLI (`dist/cli/index.js`). The same build outputs library modules under `dist/` (for example `dist/core/models.js`, `dist/core/orchestrator.js`).
+
+If you embed Refactron programmatically, import from the compiled paths your bundler resolves (check `package.json` **exports** for supported entry points in your version).
+
+---
+
+## Core layers
+
+| Layer | Role |
+|-------|------|
+| **Models** | `CodeIssue`, `BlastRadius`, `VerificationResult`, `AnalysisResult`, pipeline types — see [Models](/docs-npm/api/models) |
+| **Orchestrator** | Wires analysis → autofix → verification → backup → atomic write — see [Orchestrator](/docs-npm/api/orchestrator) |
+| **Adapters** | `ILanguageAdapter` for language-specific analyze/transform/verify — see [Adapters](/docs-npm/api/adapters) |
+| **Session (CLI)** | `WorkSessionManager` persists REPL sessions under `.refactron/work-sessions/` |
+
+---
+
+## Stability
+
+Types under `src/core/models.ts` and `src/adapters/interface.ts` are marked **LOCKED** in-repo: treat them as semver-sensitive when depending on them from outside the project.
+
+---
+
+## See also
+
+- [Core concepts](/docs-npm/concepts/blast-radius) — Blast radius and verification behavior

docs/docs-npm/cli/analyze.mdx

@@ -0,0 +1,48 @@
+---
+title: analyze
+description: Scan a path, create a work session, and open the issue browser.
+---
+
+## Usage
+
+At the REPL prompt:
+
+```
+analyze [target]
+```
+
+- **`target`** — Directory or path to scan. Defaults to `.` if omitted (parsed as the second token; see below).
+
+Examples:
+
+```
+❯ analyze .
+❯ analyze src/
+```
+
+---
+
+## Behavior
+
+1. Resolves `target` to an absolute path.
+2. Runs the analysis engine (analyzers, import/call graphs, blast radius, optional temporal data).
+3. Creates a new **work session** with a unique id and stores it under `.refactron/work-sessions/`.
+4. Sets this session as **active**.
+5. Prints a severity-grouped summary to the REPL.
+6. Opens the **interactive issue browser** automatically.
+
+If you need the browser again later, run **`issues`** (requires an active session).
+
+---
+
+## Prerequisites
+
+- Authenticated session (unless your deployment waives auth).
+- Supported language detected for the project. See [Languages](/docs-npm/languages/python).
+
+---
+
+## See also
+
+- [Work sessions](/docs-npm/concepts/sessions)
+- [Issue browser](/docs-npm/cli/issue-browser)

docs/docs-npm/cli/autofix.mdx

@@ -0,0 +1,49 @@
+---
+title: autofix
+description: Apply fixes for all fixable issues in the active session.
+---
+
+## Usage
+
+```
+autofix [--dry-run] [--verify]
+```
+
+There is **no path argument** in the REPL: autofix always uses the **active** session’s stored issues (from the last `analyze`).
+
+| Flag | Meaning |
+|------|---------|
+| `--dry-run` | Compute transforms and queue results **without** writing files |
+| `--verify` | Run the verification engine before each write (in addition to config `autofix.require_verification`) |
+
+---
+
+## Behavior
+
+1. Loads fixable issues from the active session.
+2. Reconstructs the analysis result and runs the **orchestrator** autofix pipeline (fixers → verification gate → atomic writes → backups when not dry-run).
+3. Updates the session with applied vs blocked fixes and timestamps.
+
+---
+
+## Output
+
+You will see counts for **Applied** and **Blocked**, plus any block reasons (for example verification failure). Session **phase** moves to `fixed` when updates succeed.
+
+---
+
+## Configuration
+
+Global behavior is controlled in `refactron.yaml`:
+
+- `autofix.dry_run` — Default dry-run for automation (REPL flag overrides per run when passed).
+- `autofix.require_verification` — If true, fixes that fail verification are not written.
+
+See [Configuration](/docs-npm/configuration).
+
+---
+
+## See also
+
+- [Verification](/docs-npm/cli/verify)
+- [Verification engine](/docs-npm/concepts/verification)