A clean, uv-powered Python layout let down by missing CI, type hints, and a committed production credential file.

80 of 144 checks passed across 6 categories.

• Machine Orientation

  ✓18 checks passed⚠10 problems found

  • mediumRuntime versions are pinned precisely

    An agent running the wrong runtime version hits failures it cannot diagnose.

    Checked manifest: pyproject.toml; it does not show this.

    Fix: Pin the exact runtime/language version in a .nvmrc, .python-version, or engines field.

  • lowllms.txt present

    An llms.txt is the emerging machine-orientation standard — a curated map for LLMs.

    Fix: Add an llms.txt pointing at the key docs and entry points.

  • lowTopics set

    GitHub topics situate the repo's domain and stack for an agent at a glance.

    Fix: Add a few GitHub topics describing the domain and stack.

  • lowArchitecture doc

    An ARCHITECTURE doc hands an agent the module map instead of making it infer one.

    Fix: Add an ARCHITECTURE.md describing the major components and how they fit.

  • lowExamples directory

    An examples/ directory gives an agent runnable, copyable references for the API.

    Fix: Add an examples/ directory with small, runnable usage samples.

  • lowContribution conventions are written down

    A contributor guide is where an agent learns the branch, commit, and review conventions it must follow.

    Fix: Add a CONTRIBUTING.md stating the branch naming, commit format, and how a change gets reviewed.

  • lowScope and non-goals are clear

    Knowing the boundary stops an agent from building features that were deliberately excluded.

    Nothing in the snapshot shows this.

    Fix: Add a short 'Scope' or 'Non-goals' note so the project's boundaries are explicit.

  • lowKey technical decisions are explained

    An agent that doesn't know the reasoning behind a choice will cheerfully undo it.

    Checked README § Technology Stack; it does not show this.

    Fix: Note the reasoning behind major technical decisions in the docs or an ADR directory.

  • lowA change history is accessible

    An agent reading a project cold can't tell what is fresh versus legacy without a change trail.

    Nothing in the snapshot shows this.

    Fix: Keep a CHANGELOG.md noting what changed in each version or at each notable milestone.

  • lowProject maturity is stated

    Maturity tells an agent how conservative its changes must be and whether breaking an API is acceptable.

    Nothing in the snapshot shows this.

    Fix: Add a one-line status to the README: experimental, stable, maintenance-only or archived.

  • ✓README present — An agent reconstructs what the repo is and how to work in it from the README first.
  • ✓Agent instructions file — AGENTS.md / CLAUDE.md is the direct, machine-read channel for entry points and conventions.
  • ✓Agent instructions stay lean — A bloated instructions file burns context and measurably hurts more than it helps.
  • ✓Repository description set — The one-line description is the fastest orientation signal an agent reads.
  • ✓README shows usage — A usage/example section tells an agent how the project is actually invoked.
  • ✓README states the purpose, not just the name — An agent that can't tell what a repo is for will optimise the wrong thing. Evidence: README introduction.
  • ✓Entry points are named — Knowing where execution begins saves an agent from guessing across the tree. Evidence: README § Running the Application.
  • ✓Project layout is explained — A map of the tree lets an agent localise a change without reading every folder. Evidence: README § Project Structure.
  • ✓Domain terms are defined — Undefined jargon forces an agent to infer meaning, and it infers wrong. Evidence: file tree: docs/.
  • ✓Documentation looks current — Stale docs are worse than none — an agent trusts them and acts on fiction. Evidence: file tree: README.md.
  • ✓The intended audience is clear — Knowing the intended use frames every decision an agent makes about the repo. Evidence: README introduction.
  • ✓Documentation links resolve — A dead link is a dead end an agent follows before discovering it leads nowhere. Evidence: README § Deployment.
  • ✓The stack is identifiable — An agent must know the stack before it can reason about how to change the code. Evidence: manifest: pyproject.toml.
  • ✓A single command runs it — A single obvious run command is the fastest orientation an agent can get. Evidence: README § Running the Application.
  • ✓Agent-specific guidance exists — General docs are written for humans; an agent benefits from its own orientation file. Evidence: file tree: AGENTS.md.
  • ✓External service dependencies are listed — An agent can't reason about a system's dependencies it doesn't know exist. Evidence: README § Technology Stack.
  • ✓An example shows the expected result — An example with its expected output is the cheapest way for an agent to confirm it understood the project. Evidence: README § Cast a Vote.
  • ✓Supported platforms are stated — An agent that doesn't know the supported targets can't tell a real bug from an unsupported setup. Evidence: README § Technology Stack.

• Reproducible Setup

  ✓18 checks passed⚠8 problems found

  • highSetup works from a clean clone

    Hidden setup steps are where an autonomous run silently stalls.

    Checked README § Setup; it does not show this.

    Fix: Walk the setup yourself on a clean machine and document every prerequisite and command you actually needed.

  • lowEnv template present

    A .env.example tells an agent which configuration keys it must supply to run.

    Fix: Ship a .env.example listing every required key with placeholder values.

  • lowDev container

    A .devcontainer gives an agent a one-command, fully-declared environment.

    Fix: Add a .devcontainer so the toolchain is declared, not assumed.

  • lowContainer base images are pinned

    A floating base image means the same Dockerfile builds differently over time.

    Checked file tree: Dockerfile; it does not show this.

    Fix: Pin container base images to a digest or exact version, not `latest`.

  • lowNon-idempotent steps are flagged

    An agent that reruns a non-idempotent step can silently corrupt state it relied on.

    Nothing in the snapshot shows this.

    Fix: Mark setup steps that aren't safe to rerun, or make them idempotent and say so.

  • lowTest fixtures are committed

    Tests that need data they can't get from the repo can't run in a network-isolated agent environment.

    Nothing in the snapshot shows this.

    Fix: Commit test fixtures and seed data so the suite runs without external data sources.

  • lowWhat the build produces is documented

    An agent can't verify a build whose output location and name it has to guess.

    Nothing in the snapshot shows this.

    Fix: State what the build command produces and where it lands.

  • lowThere is a way back to a clean state

    Without a clean-state command an agent debugs stale artefacts instead of the actual problem.

    Nothing in the snapshot shows this.

    Fix: Add a `clean` script or task.

  • ✓Lockfile committed — Without a lockfile two clones can resolve different dependency trees — the build isn't reproducible.
  • ✓Runtime / toolchain pinned — An unpinned runtime makes an agent guess the version a clean environment needs.
  • ✓Version pins are exact — A floating pin (a bare major, or a range) still drifts between installs.
  • ✓Container or dev-container — A Dockerfile / compose / devcontainer removes 'works on my machine' from setup.
  • ✓README documents setup — Explicit install/setup steps are what let an agent go from clone to running.
  • ✓Commands are exact and copyable — An agent runs commands verbatim — a described command is a command it has to reconstruct. Evidence: README § Setup.
  • ✓External prerequisites are listed — An agent can't install what the docs never mention it needs. Evidence: README § Technology Stack.
  • ✓Required configuration is documented — An agent that doesn't know which keys matter will run with a broken config. Evidence: README § Configuration.
  • ✓The build looks deterministic — A build that drifts means an agent's green run today is a red run tomorrow. Evidence: manifest: pyproject.toml.
  • ✓Setup avoids manual GUI steps — A click-only step is a wall an autonomous agent simply cannot get past. Evidence: README § Setup.
  • ✓It runs on sensible defaults — If nothing works until everything is configured, an agent can't get a first foothold. Evidence: README § Configuration.
  • ✓The build is self-contained — A build that reaches out to something mutable isn't reproducible across runs. Evidence: manifest: pyproject.toml.
  • ✓Setup is reasonably bounded — A sprawling setup multiplies the places an agent's run can stall. Evidence: README § Setup.
  • ✓A dependency lockfile is committed — Without a lockfile the same install command resolves to different versions on different runs. Evidence: file tree: uv.lock.
  • ✓An environment template is committed — Without a template an agent has to guess which variables exist and what they mean. Evidence: file tree: env.example.
  • ✓Setup includes a validation step — A setup that ends with no verification leaves an agent unsure whether to proceed. Evidence: README § Setup.
  • ✓The package manager is unambiguous — Competing lockfiles make an agent pick a tool at random and produce a dependency tree nobody else has. Evidence: README § Setup.
  • ✓Local runs cannot reach production by default — A shared config is how an agent's harmless local run ends up talking to a production database. Evidence: file tree: .env.production.

• Code Navigability

  ✓14 checks passed⚠8 problems found

  • low.editorconfig present

    An .editorconfig keeps whitespace and encoding consistent, so diffs stay legible.

    Fix: Add an .editorconfig pinning indentation, charset, and final-newline.

  • lowFormatter configured

    A formatter config (Prettier/Biome/rustfmt/…) keeps style uniform across the tree.

    Fix: Add a formatter (Prettier, Biome, rustfmt, …) and commit its config.

  • lowTyped public API

    A declared `types` entry gives an agent typed signatures to anchor an edit on.

    Fix: Ship type declarations and point package.json `types`/`typings` at them.

  • lowComments explain the non-obvious

    An agent can read what code does; it can't recover the reasoning that isn't written down.

    Nothing in the snapshot shows this.

    Fix: Comment the non-obvious decisions and constraints — the context that isn't in the code itself.

  • lowError handling is consistent

    Predictable error handling lets an agent reason about failure paths without surprises.

    Nothing in the snapshot shows this.

    Fix: Adopt one error-handling pattern and apply it consistently.

  • lowFew unexplained magic values

    A magic value with no name is intent an agent has to infer and may get wrong.

    Nothing in the snapshot shows this.

    Fix: Name magic values as named constants with a brief explanation.

  • lowFormatting is automated and enforced

    Manual formatting is noise an agent generates and a human has to clean up.

    Nothing in the snapshot shows this.

    Fix: Commit a formatter config and add it to CI so formatting is automatic and consistent.

  • lowHelper scripts have a home

    Findable, well-named scripts are the tools an agent reaches for first; loose ones get missed or misused.

    Nothing in the snapshot shows this.

    Fix: Move helper scripts into a scripts/ (or tools/) directory with descriptive names.

  • ✓Conventional source layout — A recognised src/ · lib/ · app/ layout lets an agent localise code without spelunking.
  • ✓Naming is consistent — Consistent naming lets an agent guess where things are instead of searching. Evidence: README § Project Structure.
  • ✓Modules have clear boundaries — Clear seams let an agent change one thing without reading everything. Evidence: README § Project Structure.
  • ✓Little obvious dead or commented-out code — Dead code is a trap an agent wastes context understanding before discarding. Judged from the snapshot as a whole; no single section settles it.
  • ✓Structure isn't pathologically nested — Deeply nested trees make an agent traverse more to find less. Evidence: README § Project Structure.
  • ✓Files have a single responsibility — A focused file is one an agent can change confidently without unrelated fallout. Evidence: README § Project Structure.
  • ✓Public boundaries are typed — Typed boundaries give an agent ground truth instead of guesses about shapes. Evidence: file tree: openapi.yaml.
  • ✓The dependency structure is legible — A tangled dependency graph makes an agent's change ripple unpredictably. Evidence: README § Project Structure.
  • ✓The data model is documented or inferrable — An agent editing a system whose data shapes are opaque will make changes that contradict the model. Evidence: README § Project Structure.
  • ✓Tests are near the code they cover — Tests an agent has to hunt for are tests it won't update when it changes the source. Evidence: README § Project Structure.
  • ✓Cross-cutting concerns are isolated — Scattered cross-cutting logic is expensive for an agent to refactor without unintended side effects. Evidence: README § Project Structure.
  • ✓Code for a feature lives together — When a feature lives in one place, an agent's change touches one area instead of a dozen folders. Evidence: README § Project Structure.
  • ✓Configuration is read in one place — Scattered configuration means an agent changes one setting and misses the three copies elsewhere. Evidence: README § Project Structure.
  • ✓Each language keeps to its own area — Interleaved languages make an agent apply the wrong toolchain and conventions to a file. Evidence: README § Project Structure.

• Verification Surface

  ✓4 checks passed⚠19 problems found

  • mediumTest command defined

    A `test` script is the documented, discoverable way to run the suite.

    Fix: Add a `test` script (package.json / Makefile / Taskfile) that runs the suite.

  • mediumCI configured

    Readable CI is the feedback loop an agent reads to know what 'green' means here.

    Fix: Add a CI workflow (e.g. under .github/workflows) that runs the build and tests.

  • mediumHow to run the tests is documented

    An agent can't check its own work if the way to verify is undocumented.

    Checked README § Running Tests; it does not show this.

    Fix: Document the exact command to run the test suite (and any setup it needs).

  • mediumVerification feedback is legible

    A noisy or flaky signal is one an agent can't tell apart from a real failure.

    Checked README § Running Tests; it does not show this.

    Fix: Make the test/CI output give an unambiguous pass/fail; quarantine or fix flaky tests.

  • mediumTests assert behaviour

    A test that asserts nothing turns green no matter how broken the code is.

    Checked file tree: tests/; it does not show this.

    Fix: Make tests assert expected outcomes, not just that code runs without throwing.

  • mediumType checking is a hard gate

    A type system only helps an agent if violations actually block a merge.

    Nothing in the snapshot shows this.

    Fix: Make the type checker a required CI step that fails the build — not a warning or informational run.

  • mediumKinds of tests are separated

    Separated suites let an agent get fast feedback before paying for the slow ones.

    Checked file tree: tests/; it does not show this.

    Fix: Split tests by kind into directories or scripts.

  • lowLint command defined

    A linter an agent can run catches a class of mistakes before they ship.

    Fix: Add a `lint` script and a linter config.

  • lowTask runner present

    A Makefile / Taskfile / justfile gives an agent a single index of the project's commands.

    Fix: Add a Makefile / Taskfile / justfile collecting the common commands.

  • lowTypecheck command

    A typecheck script lets an agent catch type errors before they ship.

    Fix: Add a `typecheck` script (e.g. `tsc --noEmit`).

  • lowBuild command

    A documented build command is the discoverable way for an agent to produce artifacts.

    Fix: Add a `build` script that produces the distributable.

  • lowCI mirrors the local checks

    If CI checks differ from local ones, an agent's local green is a false signal.

    Nothing in the snapshot shows this.

    Fix: Run the same lint/typecheck/test commands in CI that you run locally.

  • lowNo obviously broken tests committed

    A baseline that's already red gives an agent no trustworthy signal to check against.

    Checked file tree: tests/; it does not show this.

    Fix: Fix or remove broken/skipped tests so a green suite is meaningful.

  • lowEdge cases get some coverage

    Untested edge cases are where an agent's change silently breaks something.

    Checked file tree: tests/; it does not show this.

    Fix: Add tests for error paths and boundary conditions, not just the success case.

  • lowCI status is visible from the README

    An agent targeting a red codebase should know it's red before it starts.

    Nothing in the snapshot shows this.

    Fix: Add a CI status badge to the README linked to the latest pipeline run.

  • lowCoverage goes beyond example-driven tests

    An agent's generated code passes exactly the examples it was written to; property tests probe the edges it missed.

    Nothing in the snapshot shows this.

    Fix: Add property-based or mutation tests to at least the most critical subsystems.

  • lowTest names describe what they test

    A test named 'test_1' forces an agent to read the implementation to understand what failed.

    Checked file tree: tests/; it does not show this.

    Fix: Name tests to describe what they assert — 'given X, when Y, then Z' is a reliable pattern.

  • lowTest coverage is measured

    Measured coverage shows an agent which code has no safety net before it changes it.

    Nothing in the snapshot shows this.

    Fix: Add a coverage script or coverage configuration.

  • lowChecks run before a commit leaves

    Local hooks catch an agent's mistakes before they cost a CI run.

    Nothing in the snapshot shows this.

    Fix: Add pre-commit or git-hook configuration.

  • ✓Tests present — Runnable tests are the ground truth an agent checks its own edits against.
  • ✓Tests look like they cover the core — An agent trusts a green suite — a green suite that tests nothing real is a false signal. Evidence: file tree: tests/.
  • ✓The feedback loop is reasonable — If the only check takes forever, an agent's iteration loop grinds to a halt. Evidence: README § Running Tests.
  • ✓Tests run without elaborate setup — Tests an agent can't actually run are no feedback loop at all. Evidence: README § Running Tests.

• Agent Safety

  ✓11 checks passed⚠15 problems found

  • highNo committed .env

    A tracked real .env hands secrets to anything — including an agent — that reads the repo.

    Fix: Remove the .env from history, gitignore it, and ship a .env.example instead.

  • highDestructive operations are flagged

    An agent will run an unmarked destructive command the same as any other.

    Nothing in the snapshot shows this.

    Fix: Clearly label destructive/irreversible commands and gate them behind an explicit confirmation.

  • highNo hardcoded credentials in the code

    Hardcoded credentials in the tree are a breach waiting for an agent to widen the exposure.

    Checked file tree: .env.production; it does not show this.

    Fix: Remove any hardcoded credentials and move them to environment variables or a secret store.

  • mediumSecurity policy

    A SECURITY.md is where an autonomous security agent reads this repo's rules before acting on it.

    Fix: Add a SECURITY.md stating the disclosure channel and the repo's security rules.

  • mediumLicense makes the code reusable

    Without a license an agent cannot safely copy, redistribute, or vendor any of this code.

    Fix: Add a LICENSE file with an OSI-approved license so the terms of reuse are explicit.

  • medium"Don't touch" zones are stated

    Without a no-go list an agent will happily edit the one file it shouldn't.

    Checked file tree: .gitignore; it does not show this.

    Fix: Document the off-limits paths (generated, vendored, security-sensitive) in an AGENTS.md or CODEOWNERS.

  • mediumOperations follow least privilege

    Over-broad privileges turn a small agent mistake into a large blast radius.

    Checked README § API Usage; it does not show this.

    Fix: Scope tokens and permissions to the minimum each operation needs.

  • mediumThe security policy describes this system

    A scanning agent inherits its threat model from this file; boilerplate aims it at nothing in particular.

    Nothing in the snapshot shows this.

    Fix: Rewrite SECURITY.md around this system's real assets, entry points and trust boundaries.

  • mediumUntrusted input is identified

    An agent that cannot tell trusted data from untrusted input will either miss real paths or invent them.

    Nothing in the snapshot shows this.

    Fix: Name the untrusted inputs (user uploads, webhooks, fetched content) and the boundary each one crosses.

  • mediumSchema changes are versioned migrations

    Versioned migrations are reviewable and reversible; ad-hoc schema edits are neither.

    Nothing in the snapshot shows this.

    Fix: Keep schema changes as ordered migration files and document how to apply them.

  • lowCODEOWNERS present

    CODEOWNERS marks the 'don't touch without review' zones an agent should respect.

    Fix: Add a CODEOWNERS file marking the sensitive paths.

  • lowAutomated dependency updates

    Dependabot / Renovate keeps dependencies patched without a human in the loop.

    Fix: Enable Dependabot or Renovate.

  • lowCode ownership is marked

    An agent proposing changes to an owned area needs to know who to route the review to.

    Nothing in the snapshot shows this.

    Fix: Add a CODEOWNERS file mapping paths to responsible maintainers.

  • lowThe merge gate is documented

    Without a stated gate an agent doesn't know what its change must clear to be safe to land.

    Nothing in the snapshot shows this.

    Fix: Document the required checks and reviewer rules that gate a merge, in CONTRIBUTING or the README.

  • lowDependency auditing is practiced

    An agent adding a dependency needs to know audit failures will be caught before they ship.

    Nothing in the snapshot shows this.

    Fix: Add automated dependency auditing to CI and document the command to run it locally.

  • ✓No exposed secrets — Secret-shaped literals in tracked files are a live credential leak.
  • ✓.gitignore covers env files — An ignore rule for .env is what keeps the next careless commit from leaking secrets.
  • ✓.gitignore present — A .gitignore is the first guard against an agent committing secrets or build junk.
  • ✓No prompt-injection in repo text — Repo text is untrusted input; injected instructions are an attack surface, not guidance. No repository text (README, docs, description, file names) addresses automated reviewers or tries to steer a verdict.
  • ✓Secret handling is explained — If the safe path for secrets is unstated, an agent invents an unsafe one. Evidence: README § Configuration.
  • ✓Side effects are bounded — A command that reaches outside the repo can do damage an agent never anticipated. Evidence: README § Setup.
  • ✓No untrusted code executed at build — Build-time execution of remote code is a supply-chain hole an agent would walk straight into. Evidence: manifest: pyproject.toml.
  • ✓It can run sandboxed — An agent operating safely runs sandboxed; broad host access defeats that. Evidence: README § Docker.
  • ✓Secrets aren't printed or logged — A secret echoed into logs is a leak an agent will faithfully propagate. Judged from the snapshot as a whole; no single section settles it.
  • ✓Findings can be validated by running the code — A security agent that cannot exercise the code has to speculate, which is how false positives get filed. Evidence: README § Running Tests.
  • ✓Dependencies come from standard registries — Unregistered sources bypass the review and yanking that registries provide, and an agent installs them without a second look. Evidence: manifest: pyproject.toml.

• Context Economy

  ✓15 checks passed⚠4 problems found

  • lowGenerated / vendored files marked

    A .gitattributes linguist marker tells tools (and agents) what to skip.

    Fix: Mark generated/vendored paths in .gitattributes (linguist-generated / linguist-vendored).

  • lowDocs aren't duplicated or contradictory

    Conflicting docs force an agent to guess which version is true.

    Checked file tree: README.md; it does not show this.

    Fix: Keep one source of truth per topic; link to it instead of duplicating.

  • lowExamples are small and focused

    Small examples teach an agent the pattern; sprawling ones bury it.

    Checked file tree: .claude/; it does not show this.

    Fix: Trim examples to the minimum that shows each idea.

  • lowThe root is concise

    A crowded root is the first thing an agent reads and the least useful.

    Checked file tree: .claude/; it does not show this.

    Fix: Group loose root files into directories and keep only essentials at the top level.

  • ✓Dependencies not vendored in — A committed node_modules / vendor tree drowns the real signal an agent needs.
  • ✓Build output not committed — Generated dist/ · build/ output is noise an agent has to read past.
  • ✓No oversized source file — A single file in the hundreds of KB blows past an agent's effective context window.
  • ✓Documentation is signal-dense — Every token of filler is context an agent spends without getting closer to the task. Evidence: file tree: README.md.
  • ✓The tree isn't drowning in noise — A tree full of noise makes an agent work to find the few files that matter. Evidence: file tree: app/.
  • ✓The repository is focused — A grab-bag repo forces an agent to hold far more context than the task needs. Evidence: README § Project Structure.
  • ✓The files that matter are easy to find — If the important files are buried, an agent spends its budget locating them instead of editing them. Evidence: README § Project Structure.
  • ✓The README is appropriately sized — An overlong README spends an agent's context before it reaches the task. Evidence: file tree: README.md.
  • ✓Old versions aren't kept in the tree — Stale duplicates in the tree are noise an agent reads and must rule out. Evidence: file tree: .gitignore.
  • ✓The dependency list is lean — Every dependency is more surface an agent must account for when reasoning about the repo. Evidence: manifest: pyproject.toml.
  • ✓Large assets don't bloat the repo — Bulky assets inflate what an agent has to clone and scan for no signal gain. Evidence: file tree: votes.db.
  • ✓There is one canonical home for the docs — Multiple doc homes force an agent to reconcile conflicting versions of the truth. Evidence: file tree: README.md.
  • ✓Code comments don't double as an issue tracker — Inline design debates are noise an agent reads through to find the actual code logic. Judged from the snapshot as a whole; no single section settles it.
  • ✓Reference docs live outside the code — Docs embedded only in code require an agent to read the source to answer questions that belong in a doc. Evidence: file tree: docs/.
  • ✓Each tool is configured once — Overlapping configs make an agent guess which one wins. Evidence: manifest: pyproject.toml.

70 of 149 checks passed across 6 categories.

• First Impression

  ✓16 checks passed⚠11 problems found

  • mediumThe value proposition is clear

    A newcomer weighing their time wants to know what makes this worth it.

    Nothing in the snapshot shows this.

    Fix: State the project's distinctive value — what it does better or differently — early in the README.

  • mediumWhat it deliberately doesn't do is stated

    Knowing the edges early saves a newcomer from adopting it for a job it was never meant to do.

    Nothing in the snapshot shows this.

    Fix: Add a short 'Scope' or 'Non-goals' list to the README naming what the project intentionally leaves out.

  • lowTopics set

    Topics situate the project's domain at a glance and help a newcomer find it.

    Fix: Add a few GitHub topics describing the domain and stack.

  • lowStatus badges

    Build/version badges signal at a glance that the project is alive and healthy.

    Fix: Add a few status badges (CI, version, license) near the top of the README.

  • lowExamples to learn from

    An examples/ directory gives a newcomer something concrete to run and adapt.

    Fix: Add an examples/ directory with small, runnable samples.

  • lowThe project's maturity is honest

    A newcomer who mistakes a prototype for a stable tool leaves frustrated.

    Nothing in the snapshot shows this.

    Fix: State the project's status (e.g. alpha/beta/stable) near the top of the README.

  • lowThere are credibility signals

    A newcomer is deciding whether to trust strangers' code with their time.

    Nothing in the snapshot shows this.

    Fix: Surface credibility — maintainers, notable users, or a short track record — in the README.

  • lowProject status is labeled

    A newcomer discovering a project mid-pivot or post-deprecation deserves to know before they invest time.

    Nothing in the snapshot shows this.

    Fix: Add a status badge or one-line statement to the README.

  • lowBenefits are framed, not just features

    Features describe what a product has; benefits tell a newcomer why they should care.

    Checked README introduction; it does not show this.

    Fix: Rewrite the top of the README to lead with the outcome or benefit, not a feature inventory.

  • lowWhen to choose it is clear

    A newcomer comparing options needs the differentiation spelled out, not implied.

    Nothing in the snapshot shows this.

    Fix: Add a short note on when this is the right pick and when an alternative might suit better.

  • lowThe repo description and the README agree

    The description is what a newcomer sees in search results; a mismatch with the README reads as a stale or confused project.

    Checked Repository description; it does not show this.

    Fix: Rewrite the repository description so it summarises the README's opening in one line.

  • ✓README present — The README is the first screen — with none, a newcomer has nothing to land on.
  • ✓Repository description set — The one-line description sets expectations before a newcomer even opens the README.
  • ✓README shows what it does — A usage/example section lets a newcomer see the tool in action before committing.
  • ✓The README earns a newcomer's attention — A newcomer decides in seconds whether a project is worth their time. Evidence: README introduction.
  • ✓The intro avoids unexplained jargon — Jargon in the first paragraph tells a newcomer this wasn't written for them. Evidence: README introduction.
  • ✓It shows the project in action — Seeing it work is far more convincing to a newcomer than being told it works. Evidence: README § API Usage.
  • ✓The tone is welcoming — Tone signals whether questions and contributions are welcome — or merely tolerated. Evidence: README introduction.
  • ✓The opening renders cleanly — A broken first screen tells a newcomer no one's minding the shop. Evidence: README introduction.
  • ✓The README is scannable — A newcomer scans before they read; an unbroken wall makes them bounce. Evidence: README introduction.
  • ✓Claims are realistic — A newcomer who feels oversold leaves and doesn't come back. Evidence: README § Features.
  • ✓The project has a recognizable identity — A project without a visual identity is harder to remember, recommend, or find again. Evidence: Repository description.
  • ✓Key information is above the fold — A newcomer who scrolls past badges and boilerplate looking for the point often doesn't find it. Evidence: README introduction.
  • ✓The intended audience is named — A newcomer who can't tell whether they are the intended user wastes time finding out the hard way. Evidence: Repository description.
  • ✓What kind of thing it is is clear — A newcomer can't judge fit or find the right instructions until they know whether to import it, run it, or deploy it. Evidence: README introduction.
  • ✓Forks and mirrors point to the real home — A newcomer who lands on an unmarked fork or mirror files issues and pull requests where nobody is listening. Judged from the snapshot as a whole; no single section settles it.
  • ✓The README is sized to its job — A stub leaves a newcomer guessing and a sprawling manual buries the first steps; both cost the first visit. Evidence: file tree: README.md.

• Getting Running

  ✓19 checks passed⚠7 problems found

  • mediumPrerequisites are spelled out

    A newcomer can't be expected to already have the tools the maintainer takes for granted.

    Checked README § Setup; it does not show this.

    Fix: List the prerequisites up front with links or commands to install each.

  • mediumIt can be installed without building from source

    A packaged release lets a newcomer try the project in one step before committing to a full toolchain.

    Checked README § Docker; it does not show this.

    Fix: Publish a package, binary, or image and add its one-line install command to the README.

  • lowEnv template present

    A .env.example shows a newcomer exactly which settings they must fill in to run it.

    Fix: Ship a .env.example listing every required key with placeholder values.

  • lowOne-click dev container

    A .devcontainer lets a newcomer start in a cloud IDE with zero local setup.

    Fix: Add a .devcontainer for a one-click, batteries-included environment.

  • lowCommon pitfalls are covered

    The first error a newcomer hits is where they quietly give up.

    Nothing in the snapshot shows this.

    Fix: Add a short troubleshooting/FAQ section for the errors newcomers most often hit.

  • lowThere's a way to start over

    Stuck with a half-broken setup and no reset, a newcomer gives up.

    Nothing in the snapshot shows this.

    Fix: Document how to reset/clean up a botched setup so a newcomer can retry.

  • lowExpected setup time is stated

    A newcomer who expects minutes but waits an hour assumes something is broken.

    Checked README § Setup; it does not show this.

    Fix: Add a note on expected setup time so a newcomer knows whether to wait or investigate.

  • ✓Lockfile committed — Without a lockfile a newcomer's install resolves differently and hits errors the docs don't mention.
  • ✓Prerequisite versions pinned — Unpinned prerequisites are the classic 'works on my machine' first-run failure.
  • ✓One-command environment — A Dockerfile / compose / devcontainer turns a fiddly setup into one command.
  • ✓README documents setup — Explicit install steps are the difference between a 5-minute start and giving up.
  • ✓Versions pinned exactly — A floating version still drifts — a newcomer can hit a break the maintainer never saw.
  • ✓There's a real quickstart — A quick first win is what turns a curious visitor into a user. Evidence: README § Setup.
  • ✓Setup steps are in order — Out-of-order instructions strand a newcomer who can't tell what comes first. Evidence: README § Setup.
  • ✓A newcomer can confirm it worked — Without a success signal, a newcomer can't tell 'done' from 'silently broken'. Evidence: README § Running the Application.
  • ✓Commands are copy-pasteable — Reconstructing a command from prose is where a newcomer makes their first mistake. Evidence: README § Setup.
  • ✓The first run needs little config — Front-loading configuration stalls a newcomer before their first win. Evidence: README § Setup.
  • ✓There's something to try it on — A newcomer with nothing to run it on can't experience the project at all. Evidence: file tree: votes.db.
  • ✓One command bootstraps the environment — Multi-step setup multiplies the places a newcomer stalls before their first run. Evidence: README § Setup.
  • ✓The minimum viable run is fast — Every additional step before the first success is a place to lose the newcomer. Evidence: README § Setup.
  • ✓Background service setup is documented — A newcomer who can't start the dependencies cannot get the project running. Evidence: README § Docker.
  • ✓Dependencies install in one command — Manual dependency hunting is where a newcomer's first-run experience falls apart. Evidence: README § Setup.
  • ✓Required settings are explained — An env template full of unexplained names is where most newcomers stall between install and a first run. Evidence: README § Configuration.
  • ✓Setup commands match the project's tooling — A newcomer copying a command that names the wrong package manager or a missing script is stuck on step one. Evidence: README § Setup.
  • ✓Setup doesn't take over the machine — Newcomers are rightly wary of running unexplained root commands for a project they are only evaluating. Evidence: README § Setup.
  • ✓Using it and building it are separate paths — A newcomer who just wants to use it shouldn't have to wade through the contributor toolchain, and vice versa. Evidence: file tree: README.md.

• Finding Your Way

  ✓14 checks passed⚠12 problems found

  • mediumArchitecture / overview doc

    An overview hands a newcomer the map instead of making them reconstruct it.

    Fix: Add an ARCHITECTURE.md (or a 'Project layout' README section) naming the key directories.

  • mediumAn architecture overview exists

    A newcomer can't navigate a system they have no map of.

    Checked README § Project Structure; it does not show this.

    Fix: Write an architecture overview — even a short diagram and description — covering major components and their connections.

  • low.editorconfig present

    Consistent indentation/encoding keeps the code readable and diffs clean for newcomers.

    Fix: Add an .editorconfig pinning indentation, charset, and final-newline.

  • lowFormatter configured

    An auto-formatter means a newcomer never guesses the house style.

    Fix: Add a formatter (Prettier, Biome, rustfmt, …) and commit its config.

  • lowDeeper docs are discoverable

    Docs a newcomer can't find might as well not exist.

    Checked README § Deployment; it does not show this.

    Fix: Link to the docs/ directory or docs site from the README.

  • lowTerms are explained for newcomers

    Unexplained terms quietly lock a newcomer out of understanding the rest.

    Checked README § Technology Stack; it does not show this.

    Fix: Add a short glossary or define terms inline the first time they appear.

  • lowComments help a human read the code

    A newcomer learns the project by reading it; absent context, they stall.

    Nothing in the snapshot shows this.

    Fix: Comment the non-obvious parts with the intent a newcomer would otherwise miss.

  • lowThe style is predictable

    Inconsistent style makes every new file a fresh puzzle for a newcomer.

    Checked README § Project Structure; it does not show this.

    Fix: Apply a consistent, enforced style so the code reads predictably.

  • lowThe data flow is described

    Understanding the data path is often the key to understanding how the code works.

    Nothing in the snapshot shows this.

    Fix: Add a data-flow explanation or diagram to the docs.

  • lowCommon tasks are documented

    A newcomer asked to do a routine task needs the pattern, not just the tools.

    Nothing in the snapshot shows this.

    Fix: Document common task patterns as named recipes in a runbook or CONTRIBUTING guide.

  • lowThe repository root is tidy

    The root is the first thing a newcomer navigates; clutter there hides the few files that matter.

    Checked file tree: .claude/; it does not show this.

    Fix: Move loose scripts, notes, and one-off files into named folders so the root holds only top-level config, docs, and the main source directories.

  • lowGenerated and vendored code is set apart

    A newcomer who can't tell generated files from source ends up reading or editing code that gets overwritten.

    Checked file tree: .gitignore; it does not show this.

    Fix: Keep generated and vendored files in dedicated folders with obvious names such as generated, vendor, or dist.

  • ✓Conventional source layout — A familiar src/ · lib/ · app/ layout lets a newcomer guess where things live.
  • ✓No oversized source file — A single thousand-line file is a wall a newcomer bounces off.
  • ✓A newcomer can orient in the codebase — Dropped into an unmapped codebase, a newcomer doesn't know which thread to pull. Evidence: README § Project Structure.
  • ✓Key concepts are explained — A newcomer can't navigate a system whose central ideas are never named. Evidence: README § Features.
  • ✓The code is approachable — A newcomer learns the project by reading its code; cryptic code shuts that door. Evidence: README § Project Structure.
  • ✓There's something to learn from — Worked examples are the fastest way a newcomer goes from reading to doing. Evidence: README § API Usage.
  • ✓There's a suggested place to start — Dropped in with no starting point, a newcomer doesn't know which thread to pull. Evidence: README introduction.
  • ✓The documentation is organised — Information a newcomer can't locate might as well not be written. Evidence: file tree: README.md.
  • ✓The testing strategy is described — A newcomer who can't figure out the testing strategy will contribute without tests. Evidence: README § Running Tests.
  • ✓The codebase is search-friendly — Cryptic abbreviations break the simplest navigation a newcomer has. Evidence: README § Project Structure.
  • ✓The entry point is easy to spot — Knowing where the program starts gives a newcomer a thread to pull when reading the rest. Evidence: README § Project Structure.
  • ✓Tests map clearly to the code they cover — When tests sit beside or mirror their code, a newcomer finds usage examples and a safety net for each file. Evidence: file tree: tests/.
  • ✓Module boundaries show in the tree — Visible boundaries let a newcomer ignore most of the code and focus on the part their change touches. Evidence: file tree: app/.
  • ✓Docs and code use the same words — When the docs say one word and the code another, a newcomer can't connect what they read to where it lives. Evidence: README § Project Structure.

• Path to Contribute

  ✓5 checks passed⚠19 problems found

  • mediumCONTRIBUTING guide

    A CONTRIBUTING guide is the difference between a guessed and a guided first PR.

    Fix: Add a CONTRIBUTING.md covering dev setup, the test command, and how to submit a change.

  • mediumHow to contribute is explained

    Goodwill to contribute dies when the how is left as a guessing game.

    Nothing in the snapshot shows this.

    Fix: Add a CONTRIBUTING guide covering the dev setup, the change workflow, and how to open a PR.

  • mediumThe path to a first PR is clear

    A clear path is what converts a willing newcomer into an actual contributor.

    Nothing in the snapshot shows this.

    Fix: Document the end-to-end flow from change to opened PR in CONTRIBUTING.

  • lowIssue templates

    Issue templates show a newcomer how to file something useful — and that contributions are welcome.

    Fix: Add issue templates under .github/ISSUE_TEMPLATE.

  • lowPull-request template

    A PR template tells a first-time contributor what a good change includes.

    Fix: Add a PULL_REQUEST_TEMPLATE.md.

  • lowTest command defined

    A documented test command lets a contributor check their change before opening a PR.

    Fix: Add a `test` script that runs the suite.

  • lowLint command

    A linter lets a first-time contributor catch style issues before review.

    Fix: Add a `lint` script and a linter config.

  • lowTask runner

    A Makefile / Taskfile gives a contributor a single index of the project's commands.

    Fix: Add a Makefile / Taskfile collecting the common dev commands.

  • lowThere's an obvious place to start

    A newcomer who wants to help needs a small, safe task to start on.

    Nothing in the snapshot shows this.

    Fix: Label a few approachable issues as good-first-issue, or list starter tasks in CONTRIBUTING.

  • lowContribution expectations are clear

    Unstated expectations turn a first PR into a frustrating round of surprises.

    Checked file tree: AGENTS.md; it does not show this.

    Fix: State the expectations for a PR — tests, formatting, and any commit/PR conventions.

  • lowMaintainers look responsive

    A newcomer won't invest effort where contributions seem to vanish unanswered.

    Nothing in the snapshot shows this.

    Fix: Triage and respond to issues and PRs; even a quick acknowledgement keeps contributors engaged.

  • lowThe review process is explained

    Not knowing what comes next makes a newcomer hesitant to submit at all.

    Nothing in the snapshot shows this.

    Fix: Describe the review and merge process so contributors know what to expect.

  • lowContributors are recognised

    Recognition is much of what a newcomer gets back for contributing.

    Nothing in the snapshot shows this.

    Fix: Acknowledge contributors — a contributors list or credit in releases.

  • lowA PR template exists

    An unguided first PR is often missing context; a template makes the right information easy to provide.

    Nothing in the snapshot shows this.

    Fix: Add a .github/PULL_REQUEST_TEMPLATE.md guiding contributors on what to include.

  • lowThe commit convention is documented

    Undocumented commit conventions generate review churn for a contributor who guessed wrong.

    Nothing in the snapshot shows this.

    Fix: Document the expected commit format in CONTRIBUTING — even a few examples is enough.

  • lowFork-or-branch policy is stated

    A newcomer who forks when they should branch (or vice versa) starts wrong and needs correction.

    Nothing in the snapshot shows this.

    Fix: State in CONTRIBUTING whether to fork or branch and name the target branch for PRs.

  • lowCI runs on fork contributions

    A contributor who can't run CI has no feedback signal before they are reviewed.

    Nothing in the snapshot shows this.

    Fix: Ensure CI runs on external fork PRs (safe read-only jobs) so contributors see a signal before review.

  • lowContribution scope guidance exists

    A newcomer who submits a sprawling first PR learns the hard way what the project expects.

    Nothing in the snapshot shows this.

    Fix: State in CONTRIBUTING that contributions should be focused — one concern per PR.

  • lowHow to improve the docs is clear

    Docs fixes are the most common first contribution, and they stall when the source of the docs site is hidden.

    Checked file tree: docs/; it does not show this.

    Fix: Say where the docs source lives and give the command to preview it locally.

  • ✓The dev setup is documented — Contributing requires a working dev setup, which is often different from just using it. Evidence: README § Setup.
  • ✓The local dev loop is documented — Without a known edit-run-test loop, a contributor can't iterate with confidence. Evidence: README § Running Tests.
  • ✓Contributor setup isn't onerous — A heavy contributor setup filters out exactly the casual first-timers you want. Evidence: README § Setup.
  • ✓Tests run without private credentials — An outside contributor who can't run the tests can't tell whether their change broke anything. Evidence: README § Running Tests.
  • ✓No heavyweight legal gate on contributions — A CLA to sign before a typo fix turns away casual contributors and anyone who needs employer sign-off. Evidence: README § License.

• Signs of Life

  ✓8 checks passed⚠17 problems found

  • mediumCI configured

    Green CI on every change tells a newcomer the project is actively kept working.

    Fix: Add a CI workflow that runs on every push and pull request.

  • mediumReleases or versions are tracked

    Without a release trail a newcomer can't tell what they're getting or whether it's current.

    Nothing in the snapshot shows this.

    Fix: Cut tagged releases and keep a CHANGELOG so versions and changes are legible.

  • mediumMore than one person keeps it going

    A project that rests on one person stalls when they step away, and a newcomer investing time should know that.

    Nothing in the snapshot shows this.

    Fix: List the maintainers or maintaining team in the README or a maintainers file.

  • lowAutomated dependency updates

    Dependabot / Renovate activity is a visible heartbeat of ongoing maintenance.

    Fix: Enable Dependabot or Renovate.

  • lowChangelog

    A maintained CHANGELOG shows a newcomer the project ships and records its changes.

    Fix: Keep a CHANGELOG.md (e.g. the Keep a Changelog format).

  • lowFunding configured

    A FUNDING config signals an invested, sponsored project — not a one-off dump.

    Fix: Add a .github/FUNDING.yml if the project accepts sponsorship.

  • lowIssues are tended, not piled up

    A neglected tracker tells a newcomer their bug report would go nowhere.

    Nothing in the snapshot shows this.

    Fix: Triage incoming issues regularly — label, respond, and close stale ones.

  • lowThere's somewhere to get help

    A newcomer who gets stuck needs somewhere to turn that isn't a dead end.

    Nothing in the snapshot shows this.

    Fix: Point to a support channel — Discussions, a chat link, or where to ask questions.

  • lowThe project's direction is visible

    A newcomer invests more readily in a project that's clearly going somewhere.

    Checked file tree: plans/; it does not show this.

    Fix: Share a roadmap or near-term plans so newcomers see the direction.

  • lowA newcomer can pin a version

    Without a pinnable release a newcomer can't build on stable ground.

    Checked manifest: pyproject.toml; it does not show this.

    Fix: Publish tagged, versioned releases a newcomer can pin to.

  • lowIssues get responses

    A newcomer won't report or rely on something where problems vanish unheard.

    Nothing in the snapshot shows this.

    Fix: Respond to incoming issues, even briefly, so the tracker looks alive.

  • lowThere is a CI status badge

    A newcomer's first proxy for project quality is whether the build is green — a badge surfaces that immediately.

    Checked README introduction; it does not show this.

    Fix: Add a CI status badge to the README linked to the current pipeline.

  • lowA security policy is visible

    Without a stated security policy a newcomer who finds a vulnerability doesn't know what to do with it.

    Nothing in the snapshot shows this.

    Fix: Add a SECURITY.md explaining how to report a vulnerability.

  • lowKnown adopters are mentioned

    Knowing others depend on it tells a newcomer the project is worth building on.

    Nothing in the snapshot shows this.

    Fix: Add an 'Used by' or 'Adopters' section to the README, even if small.

  • lowCommunity engagement is visible

    A newcomer's first read of a project's health is how many others are invested.

    Nothing in the snapshot shows this.

    Fix: Surface community signals (badges, stats, or a brief note) in the README.

  • lowMaintenance commitment is stated

    A newcomer choosing between projects needs to know whether this one will still be maintained next year.

    Nothing in the snapshot shows this.

    Fix: State the project's maintenance commitment — actively developed, LTS, or feature-complete.

  • lowReleasing looks like a routine, not an event

    A routine release process means fixes actually ship; without one they tend to pile up on the main branch.

    Nothing in the snapshot shows this.

    Fix: Add a release workflow or tool, or document the release steps in the repo.

  • ✓Tests present — A test suite signals a project that's cared for, not abandoned.
  • ✓The project looks maintained — A newcomer hesitates to build on something that looks dead. Evidence: Repository description.
  • ✓Docs keep pace with the project — Docs that lag the code erode a newcomer's trust in everything else they read. Evidence: file tree: README.md.
  • ✓There's recent activity — A long-silent repo tells a newcomer they'd be building on abandoned ground. Evidence: Repository description.
  • ✓No unaddressed neglect warnings — An unaddressed neglect notice tells a newcomer to look elsewhere. Evidence: file tree: README.md.
  • ✓Declared dependencies look current — Dependencies frozen years back are a quiet sign nobody has touched the project, and they rarely install cleanly today. Evidence: manifest: pyproject.toml.
  • ✓Build and CI tooling is current — Config for a CI service or build tool retired years ago tells a newcomer the plumbing hasn't been touched since. Evidence: manifest: pyproject.toml.
  • ✓Tests reach the main areas of the code — Broad tests mean a newcomer's change is caught if it breaks something, and show the project is cared for. Evidence: file tree: tests/.

• Open Door

  ✓8 checks passed⚠13 problems found

  • highLicense present

    With no license the project isn't legally reusable — the door is shut however friendly the README.

    Fix: Add a LICENSE file (an OSI-approved license like MIT or Apache-2.0).

  • mediumThe license is stated the same way everywhere

    Conflicting license statements leave a newcomer unsure which terms actually apply to them.

    Checked README § License; it does not show this.

    Fix: Make the license field in every manifest and the README match the license file.

  • lowCode of conduct

    A code of conduct states the social ground rules that make it safe to step in.

    Fix: Add a CODE_OF_CONDUCT.md (the Contributor Covenant is the de-facto standard).

  • lowSecurity policy

    A SECURITY.md tells a newcomer how to report a problem responsibly.

    Fix: Add a SECURITY.md describing how to report a vulnerability.

  • lowThe project feels inclusive

    Subtle exclusion in the framing quietly narrows who feels they belong.

    Checked README introduction; it does not show this.

    Fix: Use inclusive language and a code of conduct that signals everyone is welcome.

  • lowCommunity expectations are set

    Stated ground rules are what make a newcomer feel safe to step in and ask.

    Nothing in the snapshot shows this.

    Fix: Add a CODE_OF_CONDUCT.md stating the expectations for interaction.

  • lowQuestions are explicitly welcomed

    A newcomer who isn't sure questions are welcome stays stuck in silence.

    Nothing in the snapshot shows this.

    Fix: Explicitly invite questions and name where to ask (Discussions, chat, issues).

  • lowIssue templates are provided

    An unguided first issue report is often incomplete; a template makes the right information easy to provide.

    Nothing in the snapshot shows this.

    Fix: Add .github/ISSUE_TEMPLATE/ with templates for bug reports and feature requests.

  • lowNon-code contributions are welcomed

    Many potential contributors don't feel confident coding but could meaningfully help in other ways.

    Nothing in the snapshot shows this.

    Fix: Mention in CONTRIBUTING that non-code contributions (docs, design, triage) are valued.

  • lowDecision-making is transparent

    Opaque decision-making signals to a newcomer that their input won't matter even if they engage.

    Nothing in the snapshot shows this.

    Fix: Make significant decisions public — RFCs, GitHub Discussions, or published meeting notes.

  • lowThe roadmap is public

    A newcomer who wants to contribute strategically needs to know where the project is going.

    Checked file tree: plans/; it does not show this.

    Fix: Publish a roadmap in ROADMAP.md or as GitHub milestones so newcomers can align their contributions.

  • lowThe language barrier is considered

    A project that silently assumes native fluency excludes a large group of potential contributors.

    Nothing in the snapshot shows this.

    Fix: State that non-native language contributions are welcome and that imperfect prose is fine.

  • lowResponse expectations are set honestly

    Clear expectations keep a newcomer from reading slow replies as rejection, or from waiting on help that isn't coming.

    Nothing in the snapshot shows this.

    Fix: Add a line to the README or support docs describing how and how quickly issues and questions are handled.

  • ✓The terms of use are clear — Without clear terms a newcomer can't safely adopt the project at all. Evidence: README § License.
  • ✓It doesn't assume an insider's background — Assumed background is an invisible wall a newcomer keeps walking into. Evidence: README § Setup.
  • ✓The entry barrier is low — Every hoop before the first win is a place a newcomer drops off. Evidence: README § Configuration.
  • ✓Contribution terms are clear — Unclear contribution terms are a legal question a cautious newcomer won't resolve alone. Evidence: README § License.
  • ✓It accommodates different skill levels — Material pitched only at experts shuts the door on most newcomers. Evidence: README § Setup.
  • ✓No surprise gating of core use — A bait-and-switch on core functionality burns a newcomer's goodwill instantly. Evidence: README § License.
  • ✓There are clear next steps — A newcomer who succeeds once and then hits a void quietly drifts away. Evidence: README § Deployment.
  • ✓An 'open source' claim matches the license — A newcomer who reads 'open source' and later finds non-commercial or source-available terms has been misled. Evidence: README § License.