@steipete/summarize 0.1.0

package/dist/types/content/link-preview/transcript/cache.d.ts

@@ -0,0 +1,29 @@
+import type { TranscriptCache } from '../deps.js';
+import type { CacheMode, TranscriptDiagnostics, TranscriptResolution, TranscriptSource } from '../types.js';
+export declare const DEFAULT_TTL_MS: number;
+export declare const NEGATIVE_TTL_MS: number;
+type CacheDiagnostics = Pick<TranscriptDiagnostics, 'cacheStatus' | 'notes' | 'provider' | 'textProvided' | 'cacheMode' | 'attemptedProviders'>;
+export interface CacheReadArguments {
+    url: string;
+    cacheMode: CacheMode;
+    transcriptCache: TranscriptCache | null;
+}
+export interface TranscriptCacheLookup {
+    cached: Awaited<ReturnType<TranscriptCache['get']>> | null;
+    resolution: TranscriptResolution | null;
+    diagnostics: CacheDiagnostics;
+}
+export declare const readTranscriptCache: ({ url, cacheMode, transcriptCache, }: CacheReadArguments) => Promise<TranscriptCacheLookup>;
+export declare const mapCachedSource: (source: string | null) => TranscriptSource | null;
+export declare const writeTranscriptCache: ({ url, service, resourceKey, result, transcriptCache, }: {
+    url: string;
+    service: string;
+    resourceKey: string | null;
+    result: {
+        text: string | null;
+        source: TranscriptSource | null;
+        metadata?: Record<string, unknown> | undefined;
+    };
+    transcriptCache: TranscriptCache | null;
+}) => Promise<void>;
+export {};

package/dist/types/content/link-preview/transcript/index.d.ts

@@ -0,0 +1,9 @@
+import type { LinkPreviewDeps } from '../deps.js';
+import type { CacheMode, TranscriptResolution } from '../types.js';
+import type { ProviderFetchOptions } from './types.js';
+interface ResolveTranscriptOptions {
+    youtubeTranscriptMode?: ProviderFetchOptions['youtubeTranscriptMode'];
+    cacheMode?: CacheMode;
+}
+export declare const resolveTranscriptForLink: (url: string, html: string | null, deps: LinkPreviewDeps, { youtubeTranscriptMode, cacheMode: providedCacheMode }?: ResolveTranscriptOptions) => Promise<TranscriptResolution>;
+export {};

package/dist/types/content/link-preview/transcript/normalize.d.ts

@@ -0,0 +1,3 @@
+export declare const normalizeTranscriptText: (input: string) => string;
+export declare const normalizeTranscriptLines: (lines: readonly string[]) => string | null;
+export declare const normalizeApifyTranscript: (raw: unknown) => string | null;

package/dist/types/content/link-preview/transcript/providers/generic.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderContext, ProviderFetchOptions, ProviderResult } from '../types.js';
+export declare const canHandle: () => boolean;
+export declare const fetchTranscript: (_context: ProviderContext, _options: ProviderFetchOptions) => Promise<ProviderResult>;

package/dist/types/content/link-preview/transcript/providers/podcast.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderContext, ProviderFetchOptions, ProviderResult } from '../types.js';
+export declare const canHandle: ({ url }: ProviderContext) => boolean;
+export declare const fetchTranscript: (_context: ProviderContext, _options: ProviderFetchOptions) => Promise<ProviderResult>;

package/dist/types/content/link-preview/transcript/providers/twitter.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderContext, ProviderFetchOptions, ProviderResult } from '../types.js';
+export declare const canHandle: ({ url }: ProviderContext) => boolean;
+export declare const fetchTranscript: (_context: ProviderContext, _options: ProviderFetchOptions) => Promise<ProviderResult>;

package/dist/types/content/link-preview/transcript/providers/youtube/api.d.ts

@@ -0,0 +1,26 @@
+export interface YoutubeTranscriptConfig {
+    apiKey: string;
+    context: Record<string, unknown>;
+    params: string;
+    visitorData?: string | null;
+    clientName?: string | null;
+    clientVersion?: string | null;
+    pageCl?: number | null;
+    pageLabel?: string | null;
+}
+export declare const extractYoutubeiTranscriptConfig: (html: string) => YoutubeTranscriptConfig | null;
+export declare const fetchTranscriptFromTranscriptEndpoint: (fetchImpl: typeof fetch, { config, originalUrl, }: {
+    config: YoutubeTranscriptConfig;
+    originalUrl: string;
+}) => Promise<string | null>;
+export declare const extractTranscriptFromTranscriptEndpoint: (data: unknown) => string | null;
+export declare const extractYoutubeiBootstrap: (html: string) => {
+    apiKey: string | null;
+    context: Record<string, unknown>;
+    clientVersion: string | null;
+    clientName: string | null;
+    visitorData: string | null;
+    pageCl: number | null;
+    pageLabel: string | null;
+    xsrfToken: string | null;
+} | null;

package/dist/types/content/link-preview/transcript/providers/youtube/apify.d.ts

@@ -0,0 +1 @@
+export declare const fetchTranscriptWithApify: (fetchImpl: typeof fetch, apifyApiToken: string | null, url: string) => Promise<string | null>;

package/dist/types/content/link-preview/transcript/providers/youtube/captions.d.ts

@@ -0,0 +1,7 @@
+interface YoutubeTranscriptContext {
+    html: string;
+    originalUrl: string;
+    videoId: string;
+}
+export declare const fetchTranscriptFromCaptionTracks: (fetchImpl: typeof fetch, { html, originalUrl, videoId }: YoutubeTranscriptContext) => Promise<string | null>;
+export {};

package/dist/types/content/link-preview/transcript/providers/youtube/ytdlp.d.ts

@@ -0,0 +1,3 @@
+export declare function fetchTranscriptWithYtDlp(fetchImpl: typeof fetch, url: string, { timeoutMs }?: {
+    timeoutMs?: number;
+}): Promise<string | null>;

package/dist/types/content/link-preview/transcript/providers/youtube.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderContext, ProviderFetchOptions, ProviderResult } from '../types.js';
+export declare const canHandle: ({ url }: ProviderContext) => boolean;
+export declare const fetchTranscript: (context: ProviderContext, options: ProviderFetchOptions) => Promise<ProviderResult>;

package/dist/types/content/link-preview/transcript/types.d.ts

@@ -0,0 +1,23 @@
+import type { YoutubeTranscriptMode } from '../content/types.js';
+import type { TranscriptResolution, TranscriptSource } from '../types.js';
+export type TranscriptService = 'youtube' | 'podcast' | 'generic';
+export interface ProviderContext {
+    url: string;
+    html: string | null;
+    resourceKey: string | null;
+}
+export interface ProviderFetchOptions {
+    fetch: typeof fetch;
+    apifyApiToken: string | null;
+    youtubeTranscriptMode: YoutubeTranscriptMode;
+}
+export interface ProviderResult extends TranscriptResolution {
+    metadata?: Record<string, unknown>;
+    attemptedProviders: TranscriptSource[];
+}
+export interface ProviderModule {
+    id: TranscriptService;
+    canHandle(context: ProviderContext): boolean;
+    fetchTranscript(context: ProviderContext, options: ProviderFetchOptions): Promise<ProviderResult>;
+}
+export type { TranscriptSource } from '../types.js';

package/dist/types/content/link-preview/transcript/utils.d.ts

@@ -0,0 +1,7 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare const isYouTubeUrl: (rawUrl: string) => boolean;
+export declare function isYouTubeVideoUrl(rawUrl: string): boolean;
+export declare function extractYouTubeVideoId(rawUrl: string): string | null;
+export declare function sanitizeYoutubeJsonResponse(input: string): string;
+export declare function decodeHtmlEntities(input: string): string;
+export declare function extractYoutubeBootstrapConfig(html: string): Record<string, unknown> | null;

package/dist/types/content/link-preview/types.d.ts

@@ -0,0 +1,36 @@
+export type TranscriptSource = 'youtubei' | 'captionTracks' | 'yt-dlp' | 'apify' | 'html' | 'unavailable' | 'unknown';
+export declare const CACHE_MODES: readonly ["default", "bypass"];
+export type CacheMode = (typeof CACHE_MODES)[number];
+export type CacheStatus = 'hit' | 'miss' | 'expired' | 'bypassed' | 'fallback' | 'unknown';
+export interface TranscriptDiagnostics {
+    cacheMode: CacheMode;
+    cacheStatus: CacheStatus;
+    textProvided: boolean;
+    provider: TranscriptSource | null;
+    attemptedProviders: TranscriptSource[];
+    notes?: string | null;
+}
+export interface FirecrawlDiagnostics {
+    attempted: boolean;
+    used: boolean;
+    cacheMode: CacheMode;
+    cacheStatus: CacheStatus;
+    notes?: string | null;
+}
+export interface MarkdownDiagnostics {
+    requested: boolean;
+    used: boolean;
+    provider: 'firecrawl' | 'llm' | null;
+    notes?: string | null;
+}
+export interface ContentFetchDiagnostics {
+    strategy: 'firecrawl' | 'html';
+    firecrawl: FirecrawlDiagnostics;
+    markdown: MarkdownDiagnostics;
+    transcript: TranscriptDiagnostics;
+}
+export interface TranscriptResolution {
+    text: string | null;
+    source: TranscriptSource | null;
+    diagnostics?: TranscriptDiagnostics;
+}

package/dist/types/costs.d.ts

@@ -0,0 +1,31 @@
+import type { LlmTokenUsage } from './llm/generate-text.js';
+export type LlmProvider = 'xai' | 'openai' | 'google' | 'anthropic';
+export type LlmCall = {
+    provider: LlmProvider;
+    model: string;
+    usage: LlmTokenUsage | null;
+    purpose: 'summary' | 'chunk-notes' | 'markdown';
+};
+export type RunMetricsReport = {
+    llm: Array<{
+        provider: LlmProvider;
+        model: string;
+        calls: number;
+        promptTokens: number | null;
+        completionTokens: number | null;
+        totalTokens: number | null;
+    }>;
+    services: {
+        firecrawl: {
+            requests: number;
+        };
+        apify: {
+            requests: number;
+        };
+    };
+};
+export declare function buildRunMetricsReport({ llmCalls, firecrawlRequests, apifyRequests, }: {
+    llmCalls: LlmCall[];
+    firecrawlRequests: number;
+    apifyRequests: number;
+}): RunMetricsReport;

package/dist/types/firecrawl.d.ts

@@ -0,0 +1,5 @@
+import type { ScrapeWithFirecrawl } from './content/link-preview/deps.js';
+export declare function createFirecrawlScraper({ apiKey, fetchImpl, }: {
+    apiKey: string;
+    fetchImpl: typeof fetch;
+}): ScrapeWithFirecrawl;

package/dist/types/flags.d.ts

@@ -0,0 +1,23 @@
+import type { SummaryLength } from './shared/contracts.js';
+export type YoutubeMode = 'auto' | 'web' | 'apify';
+export type FirecrawlMode = 'off' | 'auto' | 'always';
+export type MarkdownMode = 'off' | 'auto' | 'llm';
+export type StreamMode = 'auto' | 'on' | 'off';
+export type RenderMode = 'auto' | 'md' | 'md-live' | 'plain';
+export type MetricsMode = 'off' | 'on' | 'detailed';
+export type LengthArg = {
+    kind: 'preset';
+    preset: SummaryLength;
+} | {
+    kind: 'chars';
+    maxCharacters: number;
+};
+export declare function parseYoutubeMode(raw: string): YoutubeMode;
+export declare function parseFirecrawlMode(raw: string): FirecrawlMode;
+export declare function parseMarkdownMode(raw: string): MarkdownMode;
+export declare function parseStreamMode(raw: string): StreamMode;
+export declare function parseRenderMode(raw: string): RenderMode;
+export declare function parseMetricsMode(raw: string): MetricsMode;
+export declare function parseDurationMs(raw: string): number;
+export declare function parseLengthArg(raw: string): LengthArg;
+export declare function parseMaxOutputTokensArg(raw: string | undefined): number | null;

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './content/index.js';
+export * from './prompts/index.js';
+export type { SummaryLength } from './shared/contracts.js';
+export { SUMMARY_LENGTHS } from './shared/contracts.js';

package/dist/types/llm/generate-text.d.ts

@@ -0,0 +1,43 @@
+import type { ModelMessage } from 'ai';
+export type LlmApiKeys = {
+    xaiApiKey: string | null;
+    openaiApiKey: string | null;
+    googleApiKey: string | null;
+    anthropicApiKey: string | null;
+};
+export type LlmTokenUsage = {
+    promptTokens: number | null;
+    completionTokens: number | null;
+    totalTokens: number | null;
+};
+export declare function generateTextWithModelId({ modelId, apiKeys, system, prompt, temperature, maxOutputTokens, timeoutMs, fetchImpl, }: {
+    modelId: string;
+    apiKeys: LlmApiKeys;
+    system?: string;
+    prompt: string | ModelMessage[];
+    temperature?: number;
+    maxOutputTokens?: number;
+    timeoutMs: number;
+    fetchImpl: typeof fetch;
+}): Promise<{
+    text: string;
+    canonicalModelId: string;
+    provider: 'xai' | 'openai' | 'google' | 'anthropic';
+    usage: LlmTokenUsage | null;
+}>;
+export declare function streamTextWithModelId({ modelId, apiKeys, system, prompt, temperature, maxOutputTokens, timeoutMs, fetchImpl, }: {
+    modelId: string;
+    apiKeys: LlmApiKeys;
+    system?: string;
+    prompt: string | ModelMessage[];
+    temperature?: number;
+    maxOutputTokens?: number;
+    timeoutMs: number;
+    fetchImpl: typeof fetch;
+}): Promise<{
+    textStream: AsyncIterable<string>;
+    canonicalModelId: string;
+    provider: 'xai' | 'openai' | 'google' | 'anthropic';
+    usage: Promise<LlmTokenUsage | null>;
+    lastError: () => unknown;
+}>;

package/dist/types/llm/google-models.d.ts

@@ -0,0 +1,10 @@
+export declare function resolveGoogleModelForUsage({ requestedModelId, apiKey, fetchImpl, timeoutMs, }: {
+    requestedModelId: string;
+    apiKey: string;
+    fetchImpl: typeof fetch;
+    timeoutMs: number;
+}): Promise<{
+    resolvedModelId: string;
+    supportedMethods: string[];
+    note: string | null;
+}>;

package/dist/types/llm/html-to-markdown.d.ts

@@ -0,0 +1,15 @@
+import type { ConvertHtmlToMarkdown } from '../content/link-preview/deps.js';
+import type { LlmTokenUsage } from './generate-text.js';
+export declare function createHtmlToMarkdownConverter({ modelId, xaiApiKey, googleApiKey, openaiApiKey, anthropicApiKey, fetchImpl, onUsage, }: {
+    modelId: string;
+    xaiApiKey: string | null;
+    googleApiKey: string | null;
+    openaiApiKey: string | null;
+    fetchImpl: typeof fetch;
+    anthropicApiKey: string | null;
+    onUsage?: (usage: {
+        model: string;
+        provider: 'xai' | 'openai' | 'google' | 'anthropic';
+        usage: LlmTokenUsage | null;
+    }) => void;
+}): ConvertHtmlToMarkdown;

package/dist/types/llm/model-id.d.ts

@@ -0,0 +1,14 @@
+export type LlmProvider = 'xai' | 'openai' | 'google' | 'anthropic';
+export type ParsedModelId = {
+    provider: LlmProvider;
+    /**
+     * Provider-native model id (no prefix), e.g. `grok-4-fast-non-reasoning`.
+     */
+    model: string;
+    /**
+     * Canonical gateway-style id, e.g. `xai/grok-4-fast-non-reasoning`.
+     */
+    canonical: string;
+};
+export declare function normalizeGatewayStyleModelId(raw: string): string;
+export declare function parseGatewayStyleModelId(raw: string): ParsedModelId;

package/dist/types/pricing/litellm.d.ts

@@ -0,0 +1,13 @@
+import { type LiteLlmCatalog, type LiteLlmLoadResult } from 'tokentally/node';
+export type { LiteLlmCatalog, LiteLlmLoadResult };
+export declare function loadLiteLlmCatalog({ env, fetchImpl, nowMs, }: {
+    env: Record<string, string | undefined>;
+    fetchImpl: typeof fetch;
+    nowMs?: number;
+}): Promise<LiteLlmLoadResult>;
+export type LlmPerTokenPricing = {
+    inputUsdPerToken: number;
+    outputUsdPerToken: number;
+};
+export declare function resolveLiteLlmPricingForModelId(catalog: LiteLlmCatalog, modelId: string): LlmPerTokenPricing | null;
+export declare function resolveLiteLlmMaxOutputTokensForModelId(catalog: LiteLlmCatalog, modelId: string): number | null;

package/dist/types/prompts/file.d.ts

@@ -0,0 +1,6 @@
+import type { SummaryLengthTarget } from './link-summary.js';
+export declare function buildFileSummaryPrompt({ filename, mediaType, summaryLength, }: {
+    filename: string | null;
+    mediaType: string | null;
+    summaryLength: SummaryLengthTarget;
+}): string;

package/dist/types/prompts/index.d.ts

@@ -0,0 +1,3 @@
+export type { SummaryLength } from '../shared/contracts.js';
+export { buildFileSummaryPrompt } from './file.js';
+export { buildLinkSummaryPrompt, estimateMaxCompletionTokensForCharacters, pickSummaryLengthForCharacters, type ShareContextEntry, SUMMARY_LENGTH_TO_TOKENS, type SummaryLengthTarget, } from './link-summary.js';

package/dist/types/prompts/link-summary.d.ts

@@ -0,0 +1,27 @@
+import type { SummaryLength } from '../shared/contracts.js';
+export declare const SUMMARY_LENGTH_TO_TOKENS: Record<SummaryLength, number>;
+export type SummaryLengthTarget = SummaryLength | {
+    maxCharacters: number;
+};
+export declare function pickSummaryLengthForCharacters(maxCharacters: number): SummaryLength;
+export declare function estimateMaxCompletionTokensForCharacters(maxCharacters: number): number;
+export type ShareContextEntry = {
+    author: string;
+    handle?: string | null;
+    text: string;
+    likeCount?: number | null;
+    reshareCount?: number | null;
+    replyCount?: number | null;
+    timestamp?: string | null;
+};
+export declare function buildLinkSummaryPrompt({ url, title, siteName, description, content, truncated, hasTranscript, summaryLength, shares, }: {
+    url: string;
+    title: string | null;
+    siteName: string | null;
+    description: string | null;
+    content: string;
+    truncated: boolean;
+    hasTranscript: boolean;
+    summaryLength: SummaryLengthTarget;
+    shares: ShareContextEntry[];
+}): string;

package/dist/types/run.d.ts

@@ -0,0 +1,8 @@
+type RunEnv = {
+    env: Record<string, string | undefined>;
+    fetch: typeof fetch;
+    stdout: NodeJS.WritableStream;
+    stderr: NodeJS.WritableStream;
+};
+export declare function runCli(argv: string[], { env, fetch, stdout, stderr }: RunEnv): Promise<void>;
+export {};

package/dist/types/shared/contracts.d.ts

@@ -0,0 +1,2 @@
+export declare const SUMMARY_LENGTHS: readonly ["short", "medium", "long", "xl", "xxl"];
+export type SummaryLength = (typeof SUMMARY_LENGTHS)[number];

package/dist/types/summarizeHome.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Test-only hook: avoid mutating process.env (shared across Vitest worker threads).
+ * This override is scoped to the current Node worker.
+ */
+export declare function setSummarizeHomeDirOverrideForTest(dir: string | null): void;
+export declare function getSummarizeHomeDir(env: Record<string, string | undefined>): string;

package/dist/types/tty/live-markdown.d.ts

@@ -0,0 +1,10 @@
+type LiveMarkdownRenderer = {
+    render: (markdown: string) => void;
+    finish: () => void;
+};
+export declare function createLiveMarkdownRenderer({ stdout, width, color, }: {
+    stdout: NodeJS.WritableStream;
+    width: number;
+    color: boolean;
+}): LiveMarkdownRenderer;
+export {};

package/dist/types/tty/osc-progress.d.ts

@@ -0,0 +1,3 @@
+export type { OscProgressOptions } from 'osc-progress';
+export declare function startOscProgress(options: import('osc-progress').OscProgressOptions): () => void;
+export declare function supportsOscProgress(env: Record<string, string | undefined>, isTty: boolean): boolean;

package/dist/types/tty/spinner.d.ts

@@ -0,0 +1,10 @@
+export declare function startSpinner({ text, enabled, stream, }: {
+    text: string;
+    enabled: boolean;
+    stream: NodeJS.WritableStream;
+}): {
+    stop: () => void;
+    clear: () => void;
+    stopAndClear: () => void;
+    setText: (next: string) => void;
+};

package/dist/types/version.d.ts

@@ -0,0 +1,2 @@
+export declare const FALLBACK_VERSION = "0.1.0";
+export declare function resolvePackageVersion(importMetaUrl?: string): string;

package/docs/README.md

@@ -0,0 +1,11 @@
+# Docs
+
+- `docs/website.md` — normal websites (HTML extraction + Firecrawl fallback)
+- `docs/youtube.md` — YouTube transcript extraction (youtubei / captionTracks / Apify)
+- `docs/firecrawl.md` — Firecrawl mode + API key
+- `docs/llm.md` — LLM summarization + model config (Gateway/OpenAI)
+- `docs/extract-only.md` — extraction mode (no LLM call)
+
+## Website
+
+- Static site source: `docs/site/` (GitHub Pages via Actions)

package/docs/config.md

@@ -0,0 +1,28 @@
+# Config
+
+`summarize` supports an optional JSON config file for defaults.
+
+## Location
+
+Default path:
+
+- `~/.summarize/config.json`
+
+## Precedence
+
+For `model`:
+
+1. CLI flag `--model`
+2. Env `SUMMARIZE_MODEL`
+3. Config file `model`
+4. Built-in default (`google/gemini-3-flash-preview`)
+
+## Format
+
+`~/.summarize/config.json`:
+
+```json
+{
+  "model": "google/gemini-3-flash-preview"
+}
+```

package/docs/extract-only.md

@@ -0,0 +1,13 @@
+# Extract-only mode
+
+`--extract-only` prints the extracted content and exits.
+
+## Notes
+
+- No summarization LLM call happens in this mode.
+- `--markdown llm` / `--markdown auto` may still call the configured LLM for HTML → Markdown conversion.
+- `--length` is intended for summarization guidance; extraction prints full content.
+- For non-YouTube URLs, the CLI prefers Firecrawl Markdown by default when `FIRECRAWL_API_KEY` is configured.
+  - Force plain HTML extraction with `--firecrawl off`.
+- For non-YouTube URLs, `--markdown auto` can convert HTML → Markdown via an LLM when configured.
+  - Force it with `--markdown llm`.

package/docs/firecrawl.md

@@ -0,0 +1,17 @@
+# Firecrawl mode
+
+Firecrawl is a fallback for sites that block direct HTML fetching or don’t render meaningful content without JS.
+
+## `--firecrawl off|auto|always`
+
+- `off`: never use Firecrawl.
+- `auto` (default): use Firecrawl only when HTML extraction looks blocked/thin.
+- `always`: try Firecrawl first (falls back to HTML if Firecrawl is unavailable/empty).
+
+## Extract-only default
+
+When `--extract-only` is used for non-YouTube URLs and `FIRECRAWL_API_KEY` is configured, the CLI defaults to `--firecrawl always` to return Markdown.
+
+## API key
+
+- `FIRECRAWL_API_KEY` (required for Firecrawl requests)

package/docs/llm.md

@@ -0,0 +1,33 @@
+# LLM / summarization mode
+
+By default `summarize` will call an LLM using **direct provider API keys**.
+
+## Defaults
+
+- Default model: `google/gemini-3-flash-preview`
+- Override with `SUMMARIZE_MODEL`, config file (`model`), or `--model`.
+
+## Env
+
+- `XAI_API_KEY` (required for `xai/...` models)
+- `OPENAI_API_KEY` (required for `openai/...` models)
+- `OPENAI_BASE_URL` (optional; OpenAI-compatible API endpoint, e.g. OpenRouter)
+- `OPENROUTER_API_KEY` (optional; used when `OPENAI_BASE_URL` points to OpenRouter)
+- `GEMINI_API_KEY` (required for `google/...` models; also accepts `GOOGLE_GENERATIVE_AI_API_KEY` / `GOOGLE_API_KEY`)
+- `ANTHROPIC_API_KEY` (required for `anthropic/...` models)
+- `SUMMARIZE_MODEL` (optional; overrides default model selection)
+
+## Flags
+
+- `--model <model>`
+  - Examples:
+    - `google/gemini-3-flash-preview`
+    - `openai/gpt-5.2`
+    - `xai/grok-4-fast-non-reasoning`
+    - `google/gemini-2.0-flash`
+    - `anthropic/claude-sonnet-4-5`
+- `--length short|medium|long|xl|xxl|<chars>`
+  - This is *soft guidance* to the model (no hard truncation).
+- `--max-output-tokens <count>`
+  - Hard cap for output tokens (optional).
+- `--json` (includes prompt + summary in one JSON object)

package/docs/openai.md

@@ -0,0 +1,18 @@
+# OpenAI models
+
+Use OpenAI directly by choosing an `openai/...` model id.
+
+For the full model/provider matrix, see `docs/llm.md`.
+
+## Env
+
+- `OPENAI_API_KEY` (required for `openai/...` models)
+
+## Flags
+
+- `--model openai/<model>`
+- `--length short|medium|long|xl|xxl|<chars>`
+  - This is *soft guidance* to the model (no hard truncation).
+- `--max-output-tokens <count>`
+  - Hard cap for output tokens (optional).
+- `--json` (includes prompt + summary in one JSON object)

package/docs/site/.nojekyll

@@ -0,0 +1 @@
+

package/docs/site/404.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <meta name="color-scheme" content="dark light" />
+    <title>Not found — summarize</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600;700&display=swap" rel="stylesheet" />
+    <link rel="stylesheet" href="./assets/site.css" />
+  </head>
+  <body>
+    <main class="shell">
+      <header class="top">
+        <a class="brand" href="./index.html" aria-label="summarize home">
+          <span class="brand__mark" aria-hidden="true">s</span>
+          <span class="brand__word">summarize</span>
+        </a>
+      </header>
+
+      <section class="hero hero--compact">
+        <div class="hero__card">
+          <p class="kicker">404</p>
+          <h1 class="title">Page not found.</h1>
+          <p class="lede">Try the docs index or head back home.</p>
+          <div class="ctaRow">
+            <a class="btn btn--primary" href="./index.html">Home</a>
+            <a class="btn" href="./docs/index.html">Docs</a>
+          </div>
+        </div>
+      </section>
+    </main>
+
+    <script type="module" src="./assets/site.js"></script>
+  </body>
+</html>