fix path · diagnostics · public site support

Phase1 Troubleshooting

A practical guide for fixing common Phase1 issues: website caching, mobile layout, Rust builds, safe-mode behavior, VFS/storage confusion, browser/network boundaries, and public status data.

01CacheRefresh Pages. 02RustBuild checks. 03Safe modeGuardrails. 04StatusPublic marker.

fast triage

Start with the smallest check.

  1. Refresh the public page: use a fresh cache-busted URL when checking visual changes.
  2. Confirm deploy finished: verify the latest GitHub Pages workflow completed successfully.
  3. Check the local branch: pull the latest edge/stable before testing.
  4. Use the right doc: commands, security, storage, runtime, and browser issues each have dedicated pages.
  5. Keep non-claims visible: planned behavior should not be presented as implemented behavior.

github pages + cache

When the website looks unchanged, check deployment and cache.

GitHub Pages and mobile browsers can keep old CSS or JavaScript longer than expected. Cache-busted URLs help confirm that the newest static files are being loaded.

git pull

Pull the latest branch before testing locally.

gh run watch

Watch the latest Pages workflow until it succeeds.

?v=...

Use a fresh query string to bypass stale browser cache.

new tab

On iPhone, fully close the old tab if CSS still looks stale.

mobile layout

Mobile fixes should target one visible issue at a time.

The homepage has already been tuned heavily for mobile. If something looks wrong, patch the exact piece instead of reworking the whole visual system.

  • Button does not open: verify the mobile nav script and CSS cache key loaded.
  • Text is clipped: reduce the specific heading or decorative layer, not the whole layout.
  • Effects are too loud: lower opacity, blur, or animation speed in the targeted layer.
  • Layout feels crowded: tighten only the affected section first.

rust build

Use Rust checks to separate code issues from website issues.

When testing Phase1 itself, run the Rust build checks separately from website deployment checks. Website success does not prove the Rust system is working, and Rust success does not prove the site deployed.

cargo run

Run Phase1 locally from the repository.

cargo test

Run tests for regression coverage.

cargo clippy

Run lint checks where the toolchain supports it.

cargo fmt

Apply standard Rust formatting.

Open Rust runtime notes →

safe mode

Blocked host behavior should be explained, not mysterious.

If a command is blocked, determine whether it is virtual-only, host-backed, or planned. The security model explains how safe mode and host trust should be presented.

Virtual-only

The command stays inside the VFS or simulated system.

Host-backed

The command may touch the real host and should require explicit trust.

Planned

The command is part of the roadmap but not implemented in the current build.

Open safe-mode notes →

vfs + storage

Most file confusion comes from the virtual/host boundary.

When a file appears missing, first check whether it belongs to the VFS, generated system views, temporary state, persistent state, or host-backed storage.

  • Use pwd and ls to confirm the virtual location.
  • Do not assume VFS files exist on the host filesystem.
  • Do not assume generated paths are user-created files.
  • Check storage docs before trusting persistence behavior.

Open Storage + VFS guide →

browser + network

Browser behavior may be intentionally simplified.

If a page looks limited, the browser workflow may be stripping active content or exposing simplified text output. That is a boundary, not necessarily a bug.

scheme

Check whether the URL scheme is supported.

status

Inspect network status and content type where available.

content

Confirm whether scripts or forms were stripped.

output

Know where downloaded or inspected content is stored.

Open Browser + Network Safety →

status data

The public status page is generated from status data.

If roadmap percentages or public marker text look wrong, check status.json, the Pages workflow, and whether the page loaded a stale cached version.

status.html

Public status dashboard.

status.json

Machine-readable public status source.

status-badge.json

Badge-style public status source.

workflow

Pages deploy generates the public artifact.

reporting

Good reports include context.

When reporting a bug or visual issue, include the page URL, device, browser, screenshot, expected behavior, and what changed recently. For command behavior, include the command typed and the exact output.

Open GitHub issues →

non-claims

Troubleshooting docs do not imply production readiness.

This page helps diagnose website, docs, and operator-workflow issues. It does not claim Phase1 is production-ready, installer-ready, daily-driver ready, hardware-validated, security-hardened, cryptographically complete, or a complete operating system.

Back to Wiki Hub