Troubleshooting

Troubleshooting commands apply to the docs-site repository: z00z-labs/z00z-website. Route failures in the Rust workspace, wallet crates, runtime, or simulator to z00z-labs/z00z instead of trying to debug them with website-only commands.

Start From The Website Baseline

For website-repo issues, begin with:

npm ci
npm run lint
npm run verify

npm run verify is the completion gate for this repo. It covers lint, search coverage, and production build behavior.

Check You Are In The Right Repo

Wrong-repo debugging wastes time because the verification tools and file ownership are different.

If Install Fails

The fastest checks are:

Do not paste secrets, tokens, or private environment files into a public issue.

If The Dev Server Does Not Start

Run:

npm run dev

If it fails, check for:

• another process using the port;
• a dependency install that never completed cleanly;
• a content or config edit that broke startup before the target page loads.

If dev works but npm run verify later fails, the issue is usually search coverage or production build behavior rather than generic startup.

If Lint Fails

npm run lint is the fastest local signal. Common causes in this repo:

• malformed frontmatter;
• invalid imports in site files;
• content edits that broke a local rule;
• path drift after moving docs content.

Fix lint before chasing deeper build problems.

If npm run verify Fails

Name the failing lane precisely:

Do not collapse those three lanes into one vague “build broken” label.

If Search Coverage Fails

Re-check:

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

A page can read well and still become harder to discover.

If A Markdown Page Renders Incorrectly

For content issues, check the simple things first:

1. frontmatter is valid YAML;
2. headings use normal Markdown structure;
3. internal links still point at live routes;
4. Mermaid fences are closed and use supported syntax;
5. evidence sections still exist at the end of the page.

If the render issue came from a large rewrite, compare the page with nearby rewritten docs instead of inventing a new pattern.

Route And Metadata Failures

If a page 404s or lands in the wrong navigation branch, check route ownership before touching runtime code. In this repo, the usual causes are a moved Markdown file, an outdated _meta.yaml entry, a title or description drift that breaks search expectations, or an internal link that still points at an old route.

The fix is often content-level rather than framework-level. A broken docs route does not automatically mean the App Router is wrong. It may simply mean the content tree and the metadata tree no longer describe the same structure.

What To Collect Before Escalating

Collect only the smallest useful bundle:

• the exact command;
• the short error excerpt;
• the file path or route;
• whether npm run lint failed, npm run verify failed, or both;
• Node version if toolchain behavior looks suspicious.

That is enough for most website-repo issues. It is also safe to share.

Minimal Public Reproduction

A good public reproduction should be boring. It should identify the route or file, the exact command, the failing step, and the smallest visible symptom. It should not include every local experiment, every terminal screen, or every unrelated warning. Maintainers need the shortest path to the same failure, not the longest diary of how you found it.

If the smallest repro still needs sensitive material, it is no longer a normal troubleshooting case and should move to the private disclosure path.

That handoff is a safety boundary, not a debugging failure.

The correct route is part of the fix.

Wrong-repo loops are noise, not progress, during incident triage.

They also hide whether the failure is content, framework, or implementation evidence.

Shorter, cleaner handoffs usually solve the issue faster than deeper local thrashing.

A good handoff also says what source was consulted last: README.md, package.json, scripts/verify.sh, _meta.yaml, or the page itself. That detail makes it easier to see whether the next step is a docs correction, a routing correction, or a real implementation defect.

When The Problem Actually Belongs To The Core Repo

Sometimes the website appears broken because the page describes a core-project surface that is absent, renamed, or narrower than expected in z00z. In that case, treat the docs symptom and the core cause separately. The website repo may still need a wording or routing fix, but the implementation or command failure belongs in the main project repo.

This distinction matters for reproducibility. npm run verify can prove the website contract. It cannot prove that a Rust binary, wallet crate, or runtime subsystem behaves as a page implies. Once the failure crosses that boundary, the next stop is z00z, not a longer loop inside website-only troubleshooting.

When To Leave Troubleshooting And Switch Paths

Switch to Developer Support if the issue is really about repo ownership, reproduction, or cross-repo routing. Switch to Wallet Recovery Safety if anyone is pressuring you 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

Verification Rules

Troubleshooting never invents commands. Every command must exist in package.json, scripts/, or another current repository source. Public troubleshooting names the real failing step instead of using internal process labels that an external reader cannot verify.

Ordinary and sensitive errors remain distinct. A malformed Markdown file can be public. A privacy leak, support scam, or secret-bearing log must not be pasted into a normal issue.

Final Boundary

Troubleshooting is successful when it narrows the next action: fix the website repo locally, route to the core repo, or escalate privately because public detail would increase harm.

Read Next

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

Evidence and Further Reading

• github.com/z00z-labs/z00z-website, README.md, package.json, and scripts/verify.sh define the live website-repo commands referenced here.
• github.com/z00z-labs/z00z is the public main project repo for Rust workspace failures that should not be triaged with website-only commands.
• src/lib/content/ is the current website-repo 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 failure reports in a privacy-focused project.
• Privacy Threat Model And Metrics sections 7, 9, and 10 explain why troubleshooting evidence should avoid secrets, unnecessary telemetry, and oversized disclosure bundles.