Something's not quite right.
let's fix it together.

The bootstrap one-liner is only for first install (when aios doesn't exist on your machine). Once installed, aios --key <new-key> rotates in seconds.

Reports active key, server reachability, hook install state, bundle drift, conflicts. Changes nothing. Run this first when something's not working.

Compares your local bundle to the server's published version and refreshes any drift. Safe to run anytime. Recommended after a major server release.

Replays your tenant's hash-chained audit ledger and checks it against the server head. Proves your audit log is intact. Customer-runnable trust property.

Show CLI version + the full help message (same as this section).

Re-detects your project type, adds paths[] entries so test code doesn't gate on production critics. Backs up the prior config. Use --dry-run to preview first.

Removes git hook + config. Keeps your AIOS_*.md records by default (your audit history). Add --purge-docs for full removal, or --dry-run to preview.

Same content as this section but with one-click copy buttons for every command. Open at /dashboard → Help → Commands.

1. Press Win+X on your keyboard.
2. Click "Terminal" (Windows 11) or "Windows PowerShell" (Windows 10).
3. Or: press Win+R, type powershell, press Enter.
4. You're in. Now cd into your project folder before running aios --key sk-aios-….

1. Press Cmd+Space to open Spotlight.
2. Type Terminal, press Enter.
3. cd into your project folder, then run the install command.

The AI desktop app you're using doesn't ship a built-in terminal pane. AIOS installs via npm, which needs a real shell.

Two options:

1. Use your OS-level terminal once. Every Windows + macOS install has one (see the two issues above). Open it, run the install, close it. AIOS runs automatically on every git commit after that, you never need the terminal again.
2. Ask the AI itself to install it. Newer Claude Desktop + Codex Desktop versions have agentic shell tools that can run commands for you. Paste this prompt: Run this for me: irm https://aios.visnryentertainment.com/install.ps1 | iex (Windows) or Run this for me: curl -fsSL https://aios.visnryentertainment.com/install.sh | sh (macOS). The agent will execute it via its shell tool.

Mid-install, PowerShell prints a yellow warning asking "Do you want to run software from this untrusted publisher? (Y/N)".

Standard Windows execution-policy prompt. Our installer is signed but not yet EV-signed.

Type Y and press Enter. The installer proceeds normally. You can do this safely once, we don't auto-update anything afterwards.

Pasting the mac/linux curl -fsSL command into PowerShell errors out about the -fsSL flag.

Windows PowerShell aliases curl to its own Invoke-WebRequest, which has different flags.

Use the npm install instead, same result, works everywhere: Or use the PowerShell-native installer at /install.ps1.

Install crashes with ENOENT: no such file or directory, open 'CONIN$'.

Happens when the installer is run via a pipe (e.g. iex (iwr …)). Node can't open the console for the interactive Full/Minimal prompt.

Run as two separate commands instead of one pipeline:

Running aios --key … errors with node not found or similar.

Node.js isn't installed, or it's installed but not on your PATH (common after first install).

Install Node 18 or newer from nodejs.org. After install, close and reopen your terminal. PATH only refreshes for new sessions. Then re-run.

aios --key … tells you it can't find a git repo.

The folder you're in isn't a git repository yet. AIOS needs one to install its hook into.

Install looked fine, but aios doctor shows governance call works. FAIL. HTTP 401, and every git commit is rejected as unauthorized.

A small slip in the install command saved the wrong word as your API key. The two usual ones:

• aios key sk-aios-…, missing the double dash. The word "key" got saved as your key.
• aios upgrade on an older version, saved the word "upgrade" as your key.

On v5.3.33+ the CLI catches these and won't corrupt your key, but if you installed earlier the wrong value may still be saved.

Re-run the install with your real key and the double dash: Then aios doctor, the governance check should pass. Want to be sure your CLI has the latest safeguards? Run the direct reinstall first: npm install -g https://aios-governance-production.up.railway.app/package.tgz

If the command was typed correctly, the key may have been revoked (e.g. you requested a new one, which retires the old). Get a fresh key from the signup page (same email) and re-run aios --key sk-aios-NEW-KEY.

npm install stalls forever or errors with UNABLE_TO_VERIFY_LEAF_SIGNATURE, ETIMEDOUT, or proxy-related messages.

Either our server's having a moment, or your network has a proxy / corporate cert in the way.

First, check we're up: /health. If yes, configure your proxy:

Install or commit errors with timeout / connection-refused mentioning railway.app.

Either we're briefly down or your network is blocking us.

Hit /health in your browser. If it returns JSON with "status":"ok", the issue is your network. If not, check status.railway.app, we'll be back soon.

Audit log or dashboard URL points at something like 10.x.x.x rather than aios-governance-production.up.railway.app.

You're on an installer from before v5.2 that hard-coded an internal address.

Re-run the install command from your verification email. The current installer points at the right URL.

git commit succeeds normally. No PASS/WARN/GATE. No "running governance…" line.

The pre-commit hook isn't installed in this repo, usually because the install was done in a different folder.

From the project folder you want governed, re-run the key command. It re-installs the hook into this repo's .git/hooks/: The doctor will confirm the hook is wired.

You see the hook line briefly, then nothing else, commit lands silently.

Hook can't reach the server (often a network blip), or it timed out at 30s without completing.

Run aios doctor, if "server reachable" fails, see I-02.

Commits take forever; verdicts mention paths inside node_modules/, dist/, .next/, etc.

You're on an older client that didn't apply the default exclude list.

Re-run the install. v5.2 auto-excludes build artifacts, vendored deps, lockfiles, and binary blobs.

You see a subfolder treated as a submodule in git status, or AIOS can't review files inside it.

There's a nested .git/ folder inside one of your subfolders (usually from cloning a starter into a place that already has git).

Delete the nested .git:

AIOS prints a list of rule violations with line numbers, then refuses the commit.

One of AIOS's rules found a hard-blocking issue, usually a secret, an auth flaw, or a known-vulnerable dependency.

Read the output. Each line has the rule name, the file, the line number, and a short explanation. Fix those lines, git add them, and re-commit. If you're sure it's a false positive, see G-1a (Wrong file type) below, or G-02 (Bypass).

A SQL-injection check fires on a file with no SQL. A logging check fires on a CLI tool. An eval check fires on a comment that just mentions eval. A rule meant for production web code blocks a file that isn't production web code.

By default, AIOS treats every JS/TS file like production web code and runs every rule against it. aios.config.json lets you tell AIOS what kind of file each folder contains (tests / CLI / data / docs / etc.) so only the right rules run against each.

From your project root: The detector scans for tests/, scripts/proofs/, tools/, docs/, seed_data/, and adds a paths[] entry for each. Backs up the prior config to aios.config.json.pre-v5.3.bak. Preserves your custom keys.

When a commit is blocked, open the verdict in the dashboard. A yellow "Suggested config change" card shows the exact path entry that would let the file pass, plus a Copy JSON button. Paste into your aios.config.json, recommit.

Add a path entry to aios.config.json: Profiles: production (strictest), library, local_tooling, test_harness, data_extraction, knowledge_base, mixed.

Security-floor critics (secrets, owasp, crypto, auth, compliance) stay gating in every profile. You can't accidentally silence security with a config edit. AIOS rejects profiles that try. Profiles only relax style / structure critics where they don't apply.

A block is stopping a commit you need to land right now (production hotfix, etc.).

By design, that's what blocks do. There's always an escape hatch.

Use git's standard bypass flag. The commit lands and the bypass is logged in your audit trail: Use this sparingly, the bypass shows up on your dashboard as a separate review state.

If your project uses the AIOS preflight check (the script that runs before commit and asks about your AIOS_INTENT.md), the AIOS_PREFLIGHT_BYPASS=1 env var now also requires AIOS_PREFLIGHT_REASON, a free-text explanation of why you're bypassing: The reason must be at least 10 characters and not placeholder text (rejected: ok, test, fix, wip, bypass, the env-var name itself). Reason is written into your audit ledger so every bypass has a recorded rationale. This applies to the AIOS preflight script only, the git commit --no-verify form above is covered by the next entry (v5.3.55+).

If you push commits that bypassed the AIOS check (anything pushed with --no-verify, or commits made before AIOS was installed), AIOS now asks for a reason at push time, same shape as the preflight bypass above: Same validation rules: at least 10 characters, no placeholders (fix, test, asdf, etc.), not the env-var name pasted back. The reason lands in your audit log with kind: "push_bypass" alongside the commit SHAs that skipped review. Whoever runs the push provides the reason, you, your CI, or your AI agent. Closes the silent --no-verify loophole that used to let things slip through without a written record of why.

Running git commit for the first time in a freshly-installed AIOS repo, your terminal prints a long banner labeled "AIOS GOVERNANCE. FIRST COMMIT WELCOME" followed by the contents of AIOS_AGENTS.md. Subsequent commits don't show it.

By design (v5.3.9+). AIOS hands the governance rules directly to your AI agent on the first commit via the hook output channel, instead of writing into your CLAUDE.md or other vendor files. The banner is the AI's training-wheels moment, it loads the rules into context. After first commit, AIOS drops a .aios/welcomed marker and the banner never repeats.

No action needed, this is the intended behavior. The next commit will be quiet (only the verdict prints). If you want to see the welcome again (e.g. you switched AI tools and want the new agent to see it), delete .aios/welcomed and it will re-fire on the next commit.

Three things, total: AIOS_AGENTS.md (the governance rules), aios.config.json (your settings for what kind of file gets which rules), and .git/hooks/pre-commit (chained, your existing hooks are preserved). AIOS never writes to CLAUDE.md, AGENTS.md, .cursor/rules/, .github/copilot-instructions.md, or .windsurfrules. Those belong to you. AIOS never commits, never pushes, never modifies your source code.

Running aios rewrite-config errors out with Cannot find module ... v53ConfigDetector or similar. Was working previously, or never worked on a fresh install.

Older AIOS bundles were missing a small piece of the install, the detector module wasn't packaged correctly. We've since fixed it on our end.

Pull a fresh bundle: Then re-run aios rewrite-config. If aios upgrade reports "already up to date" but the error persists, you may have a stale install, reinstall with aios --key <your-key>.

A line like docs[keys[0]] or if (config.row_key) trips crypto.constantTime. "secret-dependent branch detected" or "secret-dependent memory access detected", even though the identifier is not a secret.

Older versions of the rule matched any identifier that contained the word key as a substring, so things like keys, row_key, even monkey tripped it. We've since tightened the rule so only the standalone word fires.

Pull a fresh bundle: Re-commit. If the same false positive persists on v5.3.6+ on a standalone keyword (e.g. a variable literally named key), open a feedback ticket from the dashboard, that's a separate issue.

You signed up at /signup, the page says "check your email", but nothing arrived.

Usually a spam filter or a corporate gateway. Occasionally a typo in the email field.

Three things, in order:

1. Check your spam folder. Look for sender noreply@aios.visnryentertainment.com.
2. Add aios.visnryentertainment.com to your safe senders.
3. Go back to /signup and re-submit. The previous link won't work, the new one will.

Links expire 30 minutes after sending. If yours did, just re-submit; you'll get a fresh one.

Your key worked, now you get 401 Unauthorized; or you never copied it from the verification page.

Either the 30-day beta trial elapsed, or you need a fresh key.

Re-enter the same email at /signup. We'll send a fresh verification link and issue a new key. Your previous key is revoked when the new one is issued, so re-run aios --key sk-aios-NEW-KEY in your project after.

You submitted a signup and saw a yellow box: "Did you mean name@gmail.com?"

The domain you typed is one or two characters off a major email provider (gmail.com, outlook.com, yahoo.com, icloud.com, proton.me, etc.). Most often a real typo. gmial.com, gmaill.com, gmail.cm.

Click "Use <suggestion>" to accept the correction and proceed with the corrected email. If you really meant the original (some companies use unusual domains), click "Use <original> anyway". AIOS will accept either, but the verification email only arrives at the address you confirm.

"Check your email" appeared, you waited 5+ minutes, nothing arrived, even though the domain is correct.

The most likely cause is a typo before the @ (in the username part). AIOS can detect typo'd domains but can't tell whether the username part exists at a real domain like gmail.com, it's a real address from our perspective, the bounce happens at delivery.

1. Triple-check the spelling before the @. Compare letter-by-letter against another place your email appears (an existing email client, login screen, etc.).
2. Check spam/junk one more time.
3. Re-submit at /signup with the corrected address.

If the same address fails twice and you've confirmed the spelling, contact support@visnryentertainment.com, could be a corporate spam filter blocking us at the gateway.

You signed up with a fresh email (Account B) but visiting the dashboard shows verdicts from an older account (Account A) that you previously used in this browser.

Dashboard sign-in uses a 7-day session cookie tied to whichever key you last signed in with. Your prior signin to Account A on this browser is still active.

1. Click your account menu (top-right of the dashboard) → Sign out.
2. You'll land on the sign-in page. Paste your new API key.
3. You're now on the new account's dashboard.

Alternative: re-click the original verification link from your inbox, that automatically refreshes your browser session to the new account.

You want governance on a new project, do you have to reinstall everything?

N/A, this is how it works by design.

The npm install is once per machine. The aios --key command is once per project (it installs the hook). For a new repo:

You want to stop AIOS from running on a specific repo, either to migrate off, to test something, or to clean up before sharing the repo.

From inside the project folder, run:

What's preserved by default: AIOS_MEMORY.md, AIOS_VERDICTS.md, AIOS_CODEBASE.md, AIOS_INTENT.md, AIOS_DECISION_LOG.md, AIOS_TECHNICAL_DEBT.md, AIOS_RELATIONSHIP.md, AIOS_CODEBASE_MAP.md, AIOS_TESTS.md, AIOS_COMPLIANCE.md, AIOS_SUPPLY_CHAIN.md, plus the .aios/ ledger directory. These are your governance evidence, the cryptographic record of what AIOS reviewed and when. We don't delete them automatically.

What's removed: the git pre-commit / post-commit / pre-push hooks (your originals are restored from .pre-aios backups if present), aios_user_config.json, aios.config.json, AIOS-only entries from .mcp.json (other entries preserved), the AIOS-START..AIOS-END blocks in AGENTS.md / CLAUDE.md, AIOS_AGENTS.md (if AIOS-managed), and the # AIOS section of .gitignore.

To also uninstall the global CLI: npm uninstall -g aios-governance. That removes the aios binary from your PATH.

The AIOS Governance check run on your PR shows a red failure with 401 or "Unauthorized" in the run output.

The AIOS_API_KEY secret in your GitHub repo is missing, wrong, or revoked.

1. Go to your GitHub repo → Settings → Secrets and variables → Actions.
2. Check that a secret named exactly AIOS_API_KEY exists (no typos, no extra spaces).
3. Copy your key from the dashboard Keys page and update the secret value.
4. Re-push a commit to trigger the check again.

If you recently rotated your key (getting a new one revokes the old one), you must update the GitHub secret to match.

The AIOS check run shows green and says "No governed files changed" even though there are code changes in the PR.

AIOS skips removed files, binary files (images, fonts, zips, etc.), files with zero net changes, and files over 512 KB. If your PR only touches those, there is nothing to govern.

No action needed — this is correct behavior. If you expected a specific file to be governed, check:

• The file has a text extension (e.g. .js, .ts, .py, .go — not .png, .pdf, .woff).
• The file is modified or added, not just renamed or deleted.
• The file is under 512 KB.

The GitHub Actions job fails on the step that runs curl -fsSL .../ci-runner -o aios-runner.js with a network error or 404.

The AIOS server is unreachable from GitHub's runner infrastructure, or the server URL in the workflow YAML is wrong.

1. Check your server is reachable: hit https://aios-governance-production.up.railway.app/health in a browser. It should return {"status":"ok"}.
2. Open the downloaded .github/workflows/aios.yml and confirm the server URL matches your account's server.
3. Re-download a fresh aios.yml from the dashboard GitHub Actions page and recommit.

PRs don't show any AIOS Governance check. The Actions tab shows no AIOS job either.

The workflow file is either missing, in the wrong path, or has a YAML syntax error that prevents GitHub from parsing it.

1. Confirm the file exists at exactly .github/workflows/aios.yml (not .github/aios.yml, not .github/workflow/).
2. Check the Actions tab in your GitHub repo. If AIOS doesn't appear there, the YAML is invalid. GitHub surfaces YAML parse errors under the Actions tab.
3. Re-download a fresh copy from the dashboard — the server always serves a valid template.