@oss-autopilot/core 0.58.0 → 0.59.0

package/dist/commands/comments.d.ts

@@ -16,6 +16,34 @@ interface ClaimOptions {
     issueUrl: string;
     message?: string;
 }
+/**
+ * Fetch all comments, reviews, and inline review comments for a PR.
+ * Filters out the user's own comments and optionally bot comments.
+ *
+ * @param options - Comment fetch options
+ * @param options.prUrl - Full GitHub PR URL
+ * @param options.showBots - Include bot comments (default: false)
+ * @returns Categorized comments with review, inline, and discussion sections
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ */
 export declare function runComments(options: CommentsOptions): Promise<CommentsOutput>;
+/**
+ * Post a comment on a GitHub issue or PR.
+ *
+ * @param options - Post options
+ * @param options.url - Full GitHub issue or PR URL
+ * @param options.message - Comment body text
+ * @returns Object with commentUrl (the new comment's URL) and url (the original issue/PR URL)
+ * @throws {ValidationError} If the URL or message is invalid
+ */
 export declare function runPost(options: PostOptions): Promise<PostOutput>;
+/**
+ * Post a claim comment on a GitHub issue and track it locally.
+ *
+ * @param options - Claim options
+ * @param options.issueUrl - Full GitHub issue URL
+ * @param options.message - Custom claim message (default: standard claim text)
+ * @returns URLs of the created comment and claimed issue
+ * @throws {ValidationError} If the URL or message is invalid
+ */
 export declare function runClaim(options: ClaimOptions): Promise<ClaimOutput>;

package/dist/commands/comments.js

@@ -5,6 +5,16 @@
 import { getStateManager, getOctokit, parseGitHubUrl, requireGitHubToken } from '../core/index.js';
 import { paginateAll } from '../core/pagination.js';
 import { validateUrl, validateMessage, validateGitHubUrl, PR_URL_PATTERN, ISSUE_OR_PR_URL_PATTERN, ISSUE_URL_PATTERN, } from './validation.js';
+/**
+ * Fetch all comments, reviews, and inline review comments for a PR.
+ * Filters out the user's own comments and optionally bot comments.
+ *
+ * @param options - Comment fetch options
+ * @param options.prUrl - Full GitHub PR URL
+ * @param options.showBots - Include bot comments (default: false)
+ * @returns Categorized comments with review, inline, and discussion sections
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ */
 export async function runComments(options) {
     validateUrl(options.prUrl);
     validateGitHubUrl(options.prUrl, PR_URL_PATTERN, 'PR');
@@ -96,6 +106,15 @@ export async function runComments(options) {
         },
     };
 }
+/**
+ * Post a comment on a GitHub issue or PR.
+ *
+ * @param options - Post options
+ * @param options.url - Full GitHub issue or PR URL
+ * @param options.message - Comment body text
+ * @returns Object with commentUrl (the new comment's URL) and url (the original issue/PR URL)
+ * @throws {ValidationError} If the URL or message is invalid
+ */
 export async function runPost(options) {
     validateUrl(options.url);
     validateGitHubUrl(options.url, ISSUE_OR_PR_URL_PATTERN, 'issue or PR');
@@ -122,6 +141,15 @@ export async function runPost(options) {
         url: options.url,
     };
 }
+/**
+ * Post a claim comment on a GitHub issue and track it locally.
+ *
+ * @param options - Claim options
+ * @param options.issueUrl - Full GitHub issue URL
+ * @param options.message - Custom claim message (default: standard claim text)
+ * @returns URLs of the created comment and claimed issue
+ * @throws {ValidationError} If the URL or message is invalid
+ */
 export async function runClaim(options) {
     validateUrl(options.issueUrl);
     validateGitHubUrl(options.issueUrl, ISSUE_URL_PATTERN, 'issue');

package/dist/commands/config.d.ts

@@ -13,5 +13,16 @@ export interface ConfigSetOutput {
     value: string;
 }
 export type ConfigCommandOutput = ConfigOutput | ConfigSetOutput;
+/**
+ * Read or write user configuration settings.
+ * When called without a key, returns the full config.
+ * When called with a key and value, updates the setting.
+ *
+ * @param options - Config options
+ * @param options.key - Setting key (e.g., 'username', 'add-language', 'exclude-repo')
+ * @param options.value - Setting value (required when key is provided)
+ * @returns Current config (when reading) or success confirmation (when writing)
+ * @throws {Error} If the key is unknown or the value is invalid
+ */
 export declare function runConfig(options: ConfigOptions): Promise<ConfigCommandOutput>;
 export {};

package/dist/commands/config.js

@@ -11,6 +11,17 @@ function validateScope(value) {
     }
     return value;
 }
+/**
+ * Read or write user configuration settings.
+ * When called without a key, returns the full config.
+ * When called with a key and value, updates the setting.
+ *
+ * @param options - Config options
+ * @param options.key - Setting key (e.g., 'username', 'add-language', 'exclude-repo')
+ * @param options.value - Setting value (required when key is provided)
+ * @returns Current config (when reading) or success confirmation (when writing)
+ * @throws {Error} If the key is unknown or the value is invalid
+ */
 export async function runConfig(options) {
     const stateManager = getStateManager();
     const currentConfig = stateManager.getState().config;

package/dist/commands/daily.d.ts

@@ -12,6 +12,9 @@ export { applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacit
 /**
  * Build a star filter from state for use in fetchUserPRCounts.
  * Returns undefined if no star data is available (first run).
+ *
+ * @param state - Current agent state (read-only)
+ * @returns Star filter with minimum threshold and known counts, or undefined on first run
  */
 export declare function buildStarFilter(state: Readonly<AgentState>): StarFilter | undefined;
 /**
@@ -43,15 +46,36 @@ export interface DailyCheckResult {
  *   3. updateAnalytics    — store monthly chart data
  *   4. partitionPRs       — shelve/unshelve, generate digest
  *   5. generateDigestOutput — capacity, dismiss filter, action menu assembly
+ *
+ * @param token - GitHub personal access token
+ * @returns Deduplicated daily output
+ * @throws {ConfigurationError} If no GitHub username is configured in state
  */
 export declare function executeDailyCheck(token: string): Promise<DailyOutput>;
 /**
- * Run the daily check and return deduplicated DailyOutput.
- * Errors propagate to the caller.
+ * Run the daily PR check and return a deduplicated digest.
+ *
+ * Fetches all open PRs from GitHub, computes status for each,
+ * updates repo scores, and assembles the action menu.
+ *
+ * @returns Deduplicated daily output with PR digest, capacity, and action menu
+ * @throws {ConfigurationError} If no GitHub token is available
+ *
+ * @example
+ * ```typescript
+ * import { runDaily } from '@oss-autopilot/core/commands';
+ *
+ * const output = await runDaily();
+ * console.log(output.briefSummary);
+ * console.log(`${output.actionableIssues.length} issues need attention`);
+ * ```
  */
 export declare function runDaily(): Promise<DailyOutput>;
 /**
  * Run the daily check and return the full (non-deduplicated) result.
  * Used by CLI text mode where printDigest() needs full PR objects.
+ *
+ * @returns Full daily check result with non-deduplicated PR objects
+ * @throws {ConfigurationError} If no GitHub token is available
  */
 export declare function runDailyForDisplay(): Promise<DailyCheckResult>;

package/dist/commands/daily.js

@@ -19,6 +19,9 @@ export { applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacit
 /**
  * Build a star filter from state for use in fetchUserPRCounts.
  * Returns undefined if no star data is available (first run).
+ *
+ * @param state - Current agent state (read-only)
+ * @returns Star filter with minimum threshold and known counts, or undefined on first run
  */
 export function buildStarFilter(state) {
     const minStars = state.config.minStars ?? 50;
@@ -402,6 +405,10 @@ function toDailyOutput(result) {
  *   3. updateAnalytics    — store monthly chart data
  *   4. partitionPRs       — shelve/unshelve, generate digest
  *   5. generateDigestOutput — capacity, dismiss filter, action menu assembly
+ *
+ * @param token - GitHub personal access token
+ * @returns Deduplicated daily output
+ * @throws {ConfigurationError} If no GitHub username is configured in state
  */
 export async function executeDailyCheck(token) {
     const result = await executeDailyCheckInternal(token);
@@ -436,8 +443,22 @@ async function executeDailyCheckInternal(token) {
     return generateDigestOutput(digest, activePRs, shelvedPRs, commentedIssues, failures, previousLastDigestAt);
 }
 /**
- * Run the daily check and return deduplicated DailyOutput.
- * Errors propagate to the caller.
+ * Run the daily PR check and return a deduplicated digest.
+ *
+ * Fetches all open PRs from GitHub, computes status for each,
+ * updates repo scores, and assembles the action menu.
+ *
+ * @returns Deduplicated daily output with PR digest, capacity, and action menu
+ * @throws {ConfigurationError} If no GitHub token is available
+ *
+ * @example
+ * ```typescript
+ * import { runDaily } from '@oss-autopilot/core/commands';
+ *
+ * const output = await runDaily();
+ * console.log(output.briefSummary);
+ * console.log(`${output.actionableIssues.length} issues need attention`);
+ * ```
  */
 export async function runDaily() {
     // Token is guaranteed by the preAction hook in cli.ts for non-LOCAL_ONLY_COMMANDS.
@@ -447,6 +468,9 @@ export async function runDaily() {
 /**
  * Run the daily check and return the full (non-deduplicated) result.
  * Used by CLI text mode where printDigest() needs full PR objects.
+ *
+ * @returns Full daily check result with non-deduplicated PR objects
+ * @throws {ConfigurationError} If no GitHub token is available
  */
 export async function runDailyForDisplay() {
     const token = requireGitHubToken();

package/dist/commands/detect-formatters.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Detect formatters command (#703)
+ * Scans a local repository for configured formatters/linters.
+ * Optionally diagnoses CI log output for formatting failures.
+ */
+import type { DetectFormattersOutput } from '../formatters/json.js';
+export type { DetectFormattersOutput };
+export declare function runDetectFormatters(options: {
+    repoPath?: string;
+    ciLog?: string;
+}): Promise<DetectFormattersOutput>;

package/dist/commands/detect-formatters.js

@@ -0,0 +1,24 @@
+/**
+ * Detect formatters command (#703)
+ * Scans a local repository for configured formatters/linters.
+ * Optionally diagnoses CI log output for formatting failures.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { detectFormatters, diagnoseCIFormatterFailure } from '../core/formatter-detection.js';
+import { errorMessage } from '../core/errors.js';
+export async function runDetectFormatters(options) {
+    const repoPath = path.resolve(options.repoPath ?? process.cwd());
+    const output = { ...detectFormatters(repoPath) };
+    if (options.ciLog) {
+        let logContent;
+        try {
+            logContent = fs.readFileSync(path.resolve(options.ciLog), 'utf-8');
+        }
+        catch (err) {
+            throw new Error(`Failed to read CI log file: ${errorMessage(err)}`, { cause: err });
+        }
+        output.ciDiagnosis = diagnoseCIFormatterFailure(logContent, repoPath);
+    }
+    return output;
+}

package/dist/commands/dismiss.d.ts

@@ -11,9 +11,26 @@ export interface UndismissOutput {
     undismissed: boolean;
     url: string;
 }
+/**
+ * Dismiss an issue's reply notifications without posting a comment.
+ * The dismissal auto-resurfaces when new responses arrive after the dismiss timestamp.
+ *
+ * @param options - Dismiss options
+ * @param options.url - Full GitHub issue URL
+ * @returns Whether the issue was newly dismissed (false if already dismissed)
+ * @throws {ValidationError} If the URL is not a valid GitHub issue URL
+ */
 export declare function runDismiss(options: {
     url: string;
 }): Promise<DismissOutput>;
+/**
+ * Restore a dismissed issue to notifications.
+ *
+ * @param options - Undismiss options
+ * @param options.url - Full GitHub issue URL
+ * @returns Whether the issue was undismissed (false if not currently dismissed)
+ * @throws {ValidationError} If the URL is not a valid GitHub issue URL
+ */
 export declare function runUndismiss(options: {
     url: string;
 }): Promise<UndismissOutput>;

package/dist/commands/dismiss.js

@@ -5,6 +5,15 @@
  */
 import { getStateManager } from '../core/index.js';
 import { ISSUE_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
+/**
+ * Dismiss an issue's reply notifications without posting a comment.
+ * The dismissal auto-resurfaces when new responses arrive after the dismiss timestamp.
+ *
+ * @param options - Dismiss options
+ * @param options.url - Full GitHub issue URL
+ * @returns Whether the issue was newly dismissed (false if already dismissed)
+ * @throws {ValidationError} If the URL is not a valid GitHub issue URL
+ */
 export async function runDismiss(options) {
     validateUrl(options.url);
     validateGitHubUrl(options.url, ISSUE_URL_PATTERN, 'issue');
@@ -12,6 +21,14 @@ export async function runDismiss(options) {
     const added = stateManager.dismissIssue(options.url, new Date().toISOString());
     return { dismissed: added, url: options.url };
 }
+/**
+ * Restore a dismissed issue to notifications.
+ *
+ * @param options - Undismiss options
+ * @param options.url - Full GitHub issue URL
+ * @returns Whether the issue was undismissed (false if not currently dismissed)
+ * @throws {ValidationError} If the URL is not a valid GitHub issue URL
+ */
 export async function runUndismiss(options) {
     validateUrl(options.url);
     validateGitHubUrl(options.url, ISSUE_URL_PATTERN, 'issue');

package/dist/commands/index.d.ts

@@ -59,11 +59,13 @@ export { runCheckSetup } from './setup.js';
 export { runParseList } from './parse-list.js';
 /** Check if new files are properly referenced/integrated. */
 export { runCheckIntegration } from './check-integration.js';
+/** Detect formatters/linters configured in a local repository (#703). */
+export { runDetectFormatters } from './detect-formatters.js';
 /** Scan for locally cloned repos. */
 export { runLocalRepos } from './local-repos.js';
 export type { DailyOutput, SearchOutput, StartupOutput, StatusOutput, TrackOutput } from '../formatters/json.js';
 export type { VetOutput, CommentsOutput, PostOutput, ClaimOutput } from '../formatters/json.js';
-export type { ConfigOutput, ParseIssueListOutput, CheckIntegrationOutput, LocalReposOutput, } from '../formatters/json.js';
+export type { ConfigOutput, DetectFormattersOutput, ParseIssueListOutput, CheckIntegrationOutput, LocalReposOutput, } from '../formatters/json.js';
 export type { ReadOutput } from './read.js';
 export type { ShelveOutput, UnshelveOutput } from './shelve.js';
 export type { MoveOutput, MoveTarget } from './move.js';

package/dist/commands/index.js

@@ -64,5 +64,7 @@ export { runCheckSetup } from './setup.js';
 export { runParseList } from './parse-list.js';
 /** Check if new files are properly referenced/integrated. */
 export { runCheckIntegration } from './check-integration.js';
+/** Detect formatters/linters configured in a local repository (#703). */
+export { runDetectFormatters } from './detect-formatters.js';
 /** Scan for locally cloned repos. */
 export { runLocalRepos } from './local-repos.js';

package/dist/commands/init.d.ts

@@ -6,6 +6,14 @@ export interface InitOutput {
     username: string;
     message: string;
 }
+/**
+ * Initialize with a GitHub username.
+ *
+ * @param options - Init options
+ * @param options.username - GitHub username to configure
+ * @returns Confirmation with username and next-step instructions
+ * @throws {ValidationError} If the username is invalid
+ */
 export declare function runInit(options: {
     username: string;
 }): Promise<InitOutput>;

package/dist/commands/init.js

@@ -4,6 +4,14 @@
  */
 import { getStateManager } from '../core/index.js';
 import { validateGitHubUsername } from './validation.js';
+/**
+ * Initialize with a GitHub username.
+ *
+ * @param options - Init options
+ * @param options.username - GitHub username to configure
+ * @returns Confirmation with username and next-step instructions
+ * @throws {ValidationError} If the username is invalid
+ */
 export async function runInit(options) {
     validateGitHubUsername(options.username);
     const stateManager = getStateManager();

package/dist/commands/move.d.ts

@@ -10,6 +10,16 @@ export interface MoveOutput {
     /** Human-readable description of what happened. */
     description: string;
 }
+/**
+ * Move a PR between states: attention, waiting, shelved, or auto (computed).
+ *
+ * @param options - Move options
+ * @param options.prUrl - Full GitHub PR URL
+ * @param options.target - Target state: 'attention' | 'waiting' | 'shelved' | 'auto'
+ * @returns The move result with a human-readable description
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ * @throws {Error} If the target is invalid
+ */
 export declare function runMove(options: {
     prUrl: string;
     target: string;

package/dist/commands/move.js

@@ -5,6 +5,16 @@
 import { getStateManager } from '../core/index.js';
 import { PR_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
 export const VALID_TARGETS = ['attention', 'waiting', 'shelved', 'auto'];
+/**
+ * Move a PR between states: attention, waiting, shelved, or auto (computed).
+ *
+ * @param options - Move options
+ * @param options.prUrl - Full GitHub PR URL
+ * @param options.target - Target state: 'attention' | 'waiting' | 'shelved' | 'auto'
+ * @returns The move result with a human-readable description
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ * @throws {Error} If the target is invalid
+ */
 export async function runMove(options) {
     validateUrl(options.prUrl);
     validateGitHubUrl(options.prUrl, PR_URL_PATTERN, 'PR');

package/dist/commands/search.d.ts

@@ -7,4 +7,22 @@ export { type SearchOutput } from '../formatters/json.js';
 interface SearchOptions {
     maxResults: number;
 }
+/**
+ * Search GitHub for contributable issues using multi-phase discovery.
+ *
+ * @param options - Search configuration
+ * @param options.maxResults - Maximum number of candidates to return
+ * @returns Search results with scored candidates and exclusion lists
+ * @throws {ConfigurationError} If no GitHub token is available
+ *
+ * @example
+ * ```typescript
+ * import { runSearch } from '@oss-autopilot/core/commands';
+ *
+ * const results = await runSearch({ maxResults: 10 });
+ * for (const c of results.candidates) {
+ *   console.log(`${c.issue.repo}#${c.issue.number} — ${c.viabilityScore}/100`);
+ * }
+ * ```
+ */
 export declare function runSearch(options: SearchOptions): Promise<SearchOutput>;

package/dist/commands/search.js

@@ -3,6 +3,24 @@
  * Searches for new issues to work on
  */
 import { IssueDiscovery, requireGitHubToken, getStateManager, DEFAULT_CONFIG } from '../core/index.js';
+/**
+ * Search GitHub for contributable issues using multi-phase discovery.
+ *
+ * @param options - Search configuration
+ * @param options.maxResults - Maximum number of candidates to return
+ * @returns Search results with scored candidates and exclusion lists
+ * @throws {ConfigurationError} If no GitHub token is available
+ *
+ * @example
+ * ```typescript
+ * import { runSearch } from '@oss-autopilot/core/commands';
+ *
+ * const results = await runSearch({ maxResults: 10 });
+ * for (const c of results.candidates) {
+ *   console.log(`${c.issue.repo}#${c.issue.number} — ${c.viabilityScore}/100`);
+ * }
+ * ```
+ */
 export async function runSearch(options) {
     const token = requireGitHubToken();
     const discovery = new IssueDiscovery(token);

package/dist/commands/setup.d.ts

@@ -43,6 +43,23 @@ export interface CheckSetupOutput {
     setupComplete: boolean;
     username: string;
 }
+/**
+ * Interactive setup wizard or direct setting application.
+ *
+ * Three modes:
+ * 1. `--set key=value` — Apply settings directly
+ * 2. Setup complete — Return current config
+ * 3. Setup required — Return prompts for interactive setup
+ *
+ * @param options - Setup options
+ * @param options.reset - Force re-setup even if already complete
+ * @param options.set - Key=value pairs to apply directly
+ * @returns Setup result (applied settings, current config, or setup prompts)
+ */
 export declare function runSetup(options: SetupOptions): Promise<SetupOutput>;
+/**
+ * Check whether initial setup has been completed.
+ * @returns Setup status and configured username
+ */
 export declare function runCheckSetup(): Promise<CheckSetupOutput>;
 export {};

package/dist/commands/setup.js

@@ -14,6 +14,19 @@ function parsePositiveInt(value, settingName) {
     }
     return parsed;
 }
+/**
+ * Interactive setup wizard or direct setting application.
+ *
+ * Three modes:
+ * 1. `--set key=value` — Apply settings directly
+ * 2. Setup complete — Return current config
+ * 3. Setup required — Return prompts for interactive setup
+ *
+ * @param options - Setup options
+ * @param options.reset - Force re-setup even if already complete
+ * @param options.set - Key=value pairs to apply directly
+ * @returns Setup result (applied settings, current config, or setup prompts)
+ */
 export async function runSetup(options) {
     const stateManager = getStateManager();
     const config = stateManager.getState().config;
@@ -292,6 +305,10 @@ export async function runSetup(options) {
         ],
     };
 }
+/**
+ * Check whether initial setup has been completed.
+ * @returns Setup status and configured username
+ */
 export async function runCheckSetup() {
     const stateManager = getStateManager();
     return {

package/dist/commands/shelve.d.ts

@@ -17,9 +17,25 @@ export interface UnshelveOutput {
     url: string;
 }
 export { PR_URL_PATTERN };
+/**
+ * Shelve a PR, hiding it from daily digest and capacity calculations.
+ *
+ * @param options - Shelve options
+ * @param options.prUrl - Full GitHub PR URL
+ * @returns Whether the PR was newly shelved (false if already shelved)
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ */
 export declare function runShelve(options: {
     prUrl: string;
 }): Promise<ShelveOutput>;
+/**
+ * Unshelve a PR, restoring it to the daily digest.
+ *
+ * @param options - Unshelve options
+ * @param options.prUrl - Full GitHub PR URL
+ * @returns Whether the PR was removed from the shelf (false if not shelved)
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ */
 export declare function runUnshelve(options: {
     prUrl: string;
 }): Promise<UnshelveOutput>;

package/dist/commands/shelve.js

@@ -11,6 +11,14 @@ import { getStateManager } from '../core/index.js';
 import { PR_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
 // Re-export for backward compatibility with tests
 export { PR_URL_PATTERN };
+/**
+ * Shelve a PR, hiding it from daily digest and capacity calculations.
+ *
+ * @param options - Shelve options
+ * @param options.prUrl - Full GitHub PR URL
+ * @returns Whether the PR was newly shelved (false if already shelved)
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ */
 export async function runShelve(options) {
     validateUrl(options.prUrl);
     validateGitHubUrl(options.prUrl, PR_URL_PATTERN, 'PR');
@@ -22,6 +30,14 @@ export async function runShelve(options) {
     });
     return { shelved: added, url: options.prUrl };
 }
+/**
+ * Unshelve a PR, restoring it to the daily digest.
+ *
+ * @param options - Unshelve options
+ * @param options.prUrl - Full GitHub PR URL
+ * @returns Whether the PR was removed from the shelf (false if not shelved)
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ */
 export async function runUnshelve(options) {
     validateUrl(options.prUrl);
     validateGitHubUrl(options.prUrl, PR_URL_PATTERN, 'PR');

package/dist/commands/startup.d.ts

@@ -9,13 +9,17 @@
 import { type StartupOutput, type IssueListInfo } from '../formatters/json.js';
 /**
  * Parse issueListPath from a config file's YAML frontmatter.
- * Returns the path string or undefined if not found.
+ * @param configContent - Raw content of the config.md file
+ * @returns The path string or undefined if not found
  */
 export declare function parseIssueListPathFromConfig(configContent: string): string | undefined;
 /**
  * Count available and completed items in an issue list file.
- * Available: list items (- [) NOT struck through or marked Done.
+ * Available: list items (`- [`) NOT struck through or marked Done.
  * Completed: list items that ARE struck through or marked Done.
+ *
+ * @param content - Raw markdown content of the issue list
+ * @returns Counts of available and completed items
  */
 export declare function countIssueListItems(content: string): {
     availableCount: number;
@@ -23,17 +27,22 @@ export declare function countIssueListItems(content: string): {
 };
 /**
  * Detect an issue list file from config or known paths.
- * Returns IssueListInfo or undefined if no list found.
+ * @returns Issue list info with path and item counts, or undefined if not found
  */
 export declare function detectIssueList(): IssueListInfo | undefined;
+/**
+ * Open a URL in the default system browser.
+ * @param url - URL to open
+ */
 export declare function openInBrowser(url: string): void;
 /**
  * Run startup checks and return structured output.
  * Returns StartupOutput with one of three shapes:
- * 1. Setup incomplete: { version, setupComplete: false }
- * 2. Auth failure: { version, setupComplete: true, authError: "..." }
- * 3. Success: { version, setupComplete: true, daily, dashboardUrl?, issueList? }
+ * 1. Setup incomplete: `{ version, setupComplete: false }`
+ * 2. Auth failure: `{ version, setupComplete: true, authError: "..." }`
+ * 3. Success: `{ version, setupComplete: true, daily, dashboardUrl?, issueList? }`
  *
- * Errors from the daily check propagate to the caller.
+ * @returns Startup output with auth/setup status and daily digest
+ * @throws {Error} If the daily check fails (auth or network errors propagate)
  */
 export declare function runStartup(): Promise<StartupOutput>;