Introspection: repo → manifest + gap report

The goal is a manifest.yaml that a launch strategist could work from without ever opening the repo, plus a gap report that tells the maintainer exactly what to fix before launching. Every field must be a fact found in the repository. When you propose something (e.g. a one-liner the README lacks), mark it as proposed.

1. Resolve the input

The argument is either a local path or a GitHub URL.

• Local path (Windows-first): accept backslashes, forward slashes, and paths with spaces (quoted or not). Verify the directory exists before proceeding. Never modify the target repo.
• GitHub URL: shallow-clone into the session scratchpad directory (git clone --depth 1 <url> <scratchpad>/<name>). If gh is authenticated, also fetch metadata the filesystem can't show: description, topics, stars, latest release (gh repo view <owner>/<repo> --json description,repositoryTopics,stargazerCount,latestRelease,licenseInfo). If gh is unavailable, mark those fields unknown — do not guess.

Derive slug from the repo folder name: lowercase, kebab-case, strip anything that isn't [a-z0-9-].

2. What to read (in this order)

1. README.md (or README.*) — fully. This is the primary source.
2. Package manifests: package.json, pyproject.toml, Cargo.toml, go.mod, *.gemspec, composer.json, *.csproj — name, description, keywords, license, dependencies (→ stack).
3. LICENSE* — identify the SPDX id from the text; null if absent.
4. CHANGELOG*, docs/, mkdocs.yml, docusaurus.config.* — maturity signals.
5. .github/workflows/* — CI presence; badge in README counts only if the workflow exists.
6. Test signals: test/, tests/, __tests__/, *_test.*, *.test.*, test scripts in the package manifest.
7. Visual assets: image files referenced from the README (.gif, .mp4, .png, .jpg, .svg), plus logo*, assets/, docs/images/. A demo GIF counts only if it is actually embedded in the README, not merely present in the tree.
8. External links in the README: collect every absolute URL (badges, demo/docs links, "alternative to" references) and check each one resolves — HEAD request, status < 400; fall back to GET for HEAD-hostile hosts; skip the check entirely if the session has no network and say so in the report. A URL passes in exactly three ways: it resolves; it is an explicit placeholder (<owner>-style or annotated as pending/placeholder in the surrounding text); or it sits behind a login wall and the text tells the reader to verify it logged-in. Anything else is a gap — found in this repo's own dogfood run (2026-07-19): its README hyperlinked an example project's repo that had never been published (404). Relative links are checked against the tree, not the network. Never edit the target repo to fix a link — report it.

Do NOT read the entire source tree. Sample entry points (src/main.*, index.*, cli.*) only when the README leaves category or stack ambiguous.

3. Field-by-field extraction rules

• one_liner: prefer the README's first descriptive sentence or the package manifest description. If both are missing or vague ("A tool for X"), write one from observed features and set one_liner_source: proposed. No superlatives, no adjectives that aren't demonstrated ("blazing fast" only if benchmarks are committed).
• category: one of cli | library | devtool | app | saas | framework | other. Decide from what the user actually runs/imports, not from aspiration.
• stack: what is detected (languages, frameworks, runtime), not every dependency.
• alternatives_to: only tools the README itself compares against or an obvious incumbent in the same niche ("like X but Y" phrasing). This feeds SaaSHub/AlternativeTo.
• audience.segments: use the vocabulary already present in channels/channels.yaml (devtools, webdev, security, ai, saas, indie, selfhosted, oss, general-tech, …) so the router can match channels mechanically.
• positioning.differentiators: claims the repo makes about itself. Quote or closely paraphrase; never add claims. proof_points: only verifiable facts (a benchmark file, a feature with documented usage, test coverage that exists).
• maturity.readme_quality: one honest sentence, e.g. "Clear install and usage, but no visual demo and no explanation of why this over X".
• accounts: never guess — everything starts unknown; the user fills it in (the command should tell them to).

4. The gap report — half the value of the tool

Be specific and severe. A generic "improve documentation" is a failure; the standard is "no demo GIF — blocks HN and Reddit, this is gap #1".

Rubric for impact:

• critical — blocks or severely weakens the highest-value channels (HN, Reddit, Product Hunt). Examples: no demo GIF/video in README; README doesn't say what the project does in the first two lines; no LICENSE (many channels and users will bounce).
• high — weakens several channels or the credibility of the launch post. Examples: no release/tags (nothing to announce); no install instructions that work as written; no differentiator stated anywhere ("why this over X" is unanswerable); a dead link to the repo, demo, or docs (launch-thread readers click those first).
• medium — costs reach or polish. Examples: no GitHub topics/description; no social preview image; no CHANGELOG; README has no screenshots for a visual tool.
• low — nice-to-have. Examples: no logo; no CONTRIBUTING.md; badge rot.

Each entry needs: gap (what's missing, stated plainly), impact, blocks (channel ids from channels/channels.yaml), fix (a concrete action the maintainer can do in under a day, with format/size specifics where relevant).

Group by root cause. When several gaps are faces of the same underlying state (e.g. "no public repo", "not on npm", "no release tag", "broken badges" are all "not published yet"), report ONE root entry whose gap names the root cause and whose fix is the shared remediation, with the individual faces as derived: sub-entries (each with its own gap, blocks, and optional fix detail). The root's blocks is the union of its derived blocks; its impact is the worst among them. The report must read "3 root problems", not "7 gaps" when 5 share one fix. Keep genuinely independent gaps (different fix, different owner) as separate roots.

Order root entries worst-first. If the project is genuinely launch-ready, say so — an empty gap report is a valid result, but earn it: check every rubric line before concluding.

5. Output

Write launches/<slug>/manifest.yaml following templates/manifest.template.yaml exactly (same keys, same order — the schema is a public interface, schema_version: 1). Set generated_at to today's date. Then run:

node scripts/validate-manifest.mjs launches/<slug>/manifest.yaml

and fix any errors before presenting results. In the summary to the user, lead with the top 3 gaps and state which channels they block.