This page is intentionally narrow. It only documents commands and failure modes that the current repository can support directly. If a guide tells you to run a non-local runtime command that does not exist in package.json, treat that as stale or out of scope for this repo.

Start From A Clean Baseline

Most local problems are easier to diagnose if you begin with the same known path:

npm ci
npm run lint
npm run verify

The last command matters because npm run verify is the canonical completion gate in this repo. It runs lint, search coverage, and a production build. If you skip it, you may miss a problem that only appears after a successful dev session.

If Install Fails

The fastest checks are:

If the failure is ordinary package installation trouble, do not paste secrets, tokens, or private environment files into an issue. The support path only needs the failing command, error essence, and platform details.

If The Dev Server Does Not Start

Run:

npm run dev

If it fails, check for:

• another process already using the local port;
• a dependency install that never completed cleanly;
• an earlier content or config edit that broke startup before the page you were working on even loads.

If the local page loads in dev but later fails in npm run verify, the problem is usually build-only or search-coverage related rather than a generic startup problem.

If Lint Fails

npm run lint is the fastest local quality signal. In this repo, lint failures commonly come from:

• malformed frontmatter;
• bad imports or dead code in site files;
• content edits that broke a local rule surface;
• accidental path or naming drift after moving docs content.

Fix lint before chasing deeper build problems. A large fraction of npm run verify failures are just delayed lint failures.

If npm run verify Fails

This is the most important support case because it is also the completion gate.

Do not summarize a verify failure as “build broken” if you have not checked which phase failed. The next action depends on that distinction.

If Search Coverage Fails

Search coverage failures usually mean a docs change stopped exposing the terms readers expect to find. Re-check:

• page title and description;
• nearby navigation entries;
• whether important terms disappeared from the page during a rewrite;
• whether a moved file still matches the current _meta.yaml layout.

This is one reason npm run verify is required even for pure content work. A page can read well and still become harder to discover.

If A Markdown Page Renders Incorrectly

For content issues, check the simplest things first:

1. frontmatter delimiters are valid;
2. headings use normal Markdown structure;
3. internal links still point at live doc routes;
4. include fragments remain private when they live under underscored folders;
5. any evidence section still exists at the end of the page.

If the render issue came from a big rewrite, compare the new page against the local conventions shown across the other rewritten docs rather than guessing at a new pattern.

What To Collect Before Escalating

When you need help, collect only the smallest useful bundle:

• the command you ran;
• the exact error line or short summary;
• the file path you edited;
• whether npm run lint and npm run verify both fail or only one does;
• your Node version if install or toolchain behavior looks suspicious.

That is enough for most docs-repo issues. It is also safe to share. Do not include secrets, private keys, or wallet recovery data in a support request.

When To Leave Troubleshooting And Switch Paths

Switch to Developer Support if the problem is really about reproduction, repo workflow, or a multi-file contributor issue. Switch to Wallet Recovery Safety if the user is under pressure to reveal secret material. Switch to /docs/security if the failure looks like a privacy leak, exploit path, or trusted-channel impersonation problem.

Troubleshooting Flowchart

If Mermaid, Icons, Or Frontmatter Fail

Mermaid failures usually come from an unclosed fence, unsupported syntax, or a diagram placed in a file that was intended to be frontmatter-only. Icon failures usually come from older circle-outline difficulty values rather than the Phase 002 mdi:alphabet-*-box-outline contract. Frontmatter failures usually come from quoting, colons inside descriptions, or accidental body text in an index file. Fix these before changing runtime code. Most content rendering anomalies are content contract problems, not route-engine problems.

Route And Content Checks

When a page 404s, check the route file and metadata before touching application code. A docs page normally needs a Markdown file under the correct domain folder, an entry in the relevant _meta.yaml when ordered navigation matters, valid frontmatter, and a supported slug. If the route is an index, remember the active rule: content/**/index.md files contain only YAML frontmatter. Body content belongs in child pages, not in index files.

When search coverage fails, compare the page count, title, description, and domain order. Search coverage is not only a build check; it is a discoverability contract. A page can render and still fail the docs product if it disappears from search or uses stale metadata.

Escalation Package

A good troubleshooting escalation contains the command, exact output excerpt, changed files, route, expected behavior, observed behavior, and whether the issue is security-sensitive. Do not send full logs when a short error essence is enough. Do not include .env, secrets, wallet material, or private support transcripts.

Review Notes

Troubleshooting pages should never invent commands. Every command should exist in package.json, scripts/, or another current repo source. If a command is conceptual or future-facing, do not put it in a troubleshooting step. A user following troubleshooting instructions should be able to run the command locally and see a meaningful result.

The page should also preserve the difference between ordinary errors and sensitive errors. A malformed Markdown file can be public. A privacy leak, support scam, or secret-bearing log should not be pasted into a normal issue merely because it appeared during a build or rendering problem.

Final Boundary

Troubleshooting is successful when it narrows the next action. If the page leaves the user choosing between lint, search coverage, build, route metadata, and security escalation without evidence, it has not done its job.

Read Next

Read Developer Support for builder routing, Supply Chain for dependency or asset questions, and Responsible Disclosure for sensitive failures.

Evidence and Further Reading

• README.md documents the supported local setup flow, including the Node requirement and the primary npm commands referenced here.
• package.json defines the live scripts for dev, lint, verify:search, and verify.
• scripts/verify.sh is the repo-local source of truth showing that npm run verify runs lint, search coverage, and a production build.
• src/lib/content/ is the current repo-local content-loading surface to inspect when route, rendering, or metadata behavior needs implementation evidence.
• Main Whitepaper sections 10, 12, and Appendix C explain why narrow, reproducible evidence matters more than vague “it failed somehow” reporting in a privacy-focused project.
• Privacy Threat Model And Metrics section 10 and sections 7 and 9 explain why troubleshooting evidence should avoid secrets, unnecessary telemetry, and oversized disclosure bundles.