@ornexus/neocortex 4.59.1

package/docs/install/coderabbit-manual-setup.md

@@ -0,0 +1,86 @@
+# CodeRabbit manual setup
+
+Story: `P177.04`
+
+Evidence placeholder: `[P177-EV-CODERABBIT-OPTIN]`
+
+This guide documents the public-safe CodeRabbit setup boundary for Neocortex
+installs. CodeRabbit is an optional third-party tool. Neocortex default npm
+install, global postinstall, `install.sh`, and `install.ps1` do not install it or
+run vendor onboarding flows.
+
+## Default Neocortex install behavior
+
+Default installation only reports CodeRabbit status as an informational optional
+tool check:
+
+```text
+CodeRabbit CLI optional setup skipped: P177_OPTIONAL_TOOL_SKIPPED_NONINTERACTIVE
+```
+
+The exact installer output can vary by platform and quiet mode, but the contract
+is stable:
+
+- no CodeRabbit network installer is invoked by default;
+- no shell-piped vendor installer, package-manager install, doctor check, auth
+  flow, browser flow, or shell profile mutation is started by Neocortex;
+- absence of CodeRabbit is non-blocking for Neocortex installation;
+- CI and non-interactive runs use public reason codes such as
+  `P177_OPTIONAL_TOOL_SKIPPED_CI` or
+  `P177_OPTIONAL_TOOL_SKIPPED_NONINTERACTIVE`.
+
+## Manual setup boundary
+
+If a user wants CodeRabbit, they must install and authenticate it outside the
+Neocortex npm lifecycle by following CodeRabbit's own current public
+documentation. Review any third-party installer before running it because it may
+change `PATH`, inspect the local environment, run doctor checks, or require
+browser authentication.
+
+Neocortex does not define a default CodeRabbit opt-in flag for npm `postinstall`.
+Until a future public contract adds one, setup is manual: install the third-party
+tool separately, authenticate with the vendor separately, and then rerun
+Neocortex commands. Keep vendor output out of Neocortex issues and release
+evidence; summarize only public reason codes and synthetic paths.
+
+After manual setup, Neocortex may detect that a `coderabbit` command is already
+available and report it as an optional/manual tool. Neocortex still does not run
+CodeRabbit installation or onboarding during default install.
+
+## Public-safe diagnostics
+
+Use synthetic summaries and reason codes in support reports:
+
+```json
+{
+  "tool": "coderabbit",
+  "phase": "optional-tool-setup",
+  "status": "skipped",
+  "reasonCode": "P177_OPTIONAL_TOOL_OPT_IN_REQUIRED",
+  "summary": "Optional CodeRabbit setup is manual and outside default Neocortex install."
+}
+```
+
+Installer stdout may render the same information as bounded key/value text, for
+example `reasonCode=P177_OPTIONAL_TOOL_SKIPPED_CI` with `code=null`,
+`signal=null`, `timedOut=false` and `redactionReasonCode=P177_PUBLIC_SAFE_LOG_REDACTED`.
+See `docs/install/installer-diagnostics.md` for the shared diagnostics contract.
+
+If support asks whether CodeRabbit was installed by default, answer with the
+diagnostic reason code and this contract: default Neocortex postinstall skips
+third-party installers and reports only optional/manual status. Do not paste raw
+CodeRabbit onboarding, browser-auth prompts, shell profile diffs, or terminal
+transcripts.
+
+Do not paste raw vendor onboarding output, terminal transcripts, private paths,
+license keys, tokens, customer data, or browser-auth details into issues, docs,
+tests, or project memory.
+
+## Traceability
+
+| Story item | Contract | Validation |
+| --- | --- | --- |
+| `P177-REQ-04` | `P177-CON-OPT-01`, `P177-CON-DIAG-01`, `P177-CON-TARBALL-01` | `P177-VAL-04` / `[P177-EV-CODERABBIT-OPTIN]` |
+| T2 / AC1 | Default postinstall does not invoke CodeRabbit installers. | Fake `curl`, `npm`, and `coderabbit` tests under `scripts/test-tier3-install.sh`. |
+| T3 / AC2 / AC3 | Setup is manual, CI/non-interactive skips emit public reason codes. | This document and installer script diagnostics. |
+| T4 / AC4 | Missing CodeRabbit is informational and non-blocking. | Installer scripts return success from the optional status check. |

package/docs/install/installer-diagnostics.md

@@ -0,0 +1,107 @@
+# Installer diagnostics and optional-tool skips
+
+Story: `P177.05`
+
+Evidence placeholder: `[P177-EV-DIAGNOSTICS]`
+
+Neocortex installer diagnostics are public-safe summaries. They use stable P177
+reason codes and bounded metadata only. Do not attach raw npm lifecycle logs,
+third-party onboarding output, private local paths, tokens, license keys or
+customer data to support issues.
+
+## Optional tool diagnostics
+
+Default npm lifecycle installs do not run CodeRabbit or similar third-party
+installers. CI and non-interactive runs report a skip summary such as:
+
+```text
+[neocortex-installer] tool=coderabbit phase=optional-tool-setup status=skipped reasonCode=P177_OPTIONAL_TOOL_SKIPPED_CI code=null signal=null timedOut=false retryAttempt=0 timeoutMs=0 docPath=docs/install/coderabbit-manual-setup.md redactionReasonCode=P177_PUBLIC_SAFE_LOG_REDACTED summary=optional_tool_setup_skipped
+```
+
+Stable skip and opt-in reason codes:
+
+- `P177_OPTIONAL_TOOL_SKIPPED_CI`
+- `P177_OPTIONAL_TOOL_SKIPPED_NONINTERACTIVE`
+- `P177_OPTIONAL_TOOL_OPT_IN_REQUIRED`
+- `P177_OPTIONAL_TOOL_DETECTED_MANUAL`
+
+Optional child failures, if a future explicit opt-in path runs one, remain
+fail-open and use bounded summaries such as `P177_OPTIONAL_TOOL_SIGNAL`,
+`P177_OPTIONAL_TOOL_TIMEOUT` or `P177_OPTIONAL_TOOL_SPAWN_ERROR`.
+
+## Enterprise continuity SQLite adapter
+
+Enterprise continuity commands use a project-local SQLite store only when the
+optional `better-sqlite3` adapter is available. Base `neocortex-client` commands
+continue to start without this native adapter. If an Enterprise continuity command
+needs durable SQLite and the adapter is missing or cannot load, it must stop before
+creating or mutating `.neocortex/continuity` and return public reason code
+`sqlite-adapter-unavailable` with bounded guidance:
+
+```text
+npm install --workspace packages/client better-sqlite3 --include=optional
+```
+
+Doctor output must remain public-safe: report only the adapter status, SQLite file
+relative path, WAL/integrity status and reason codes such as
+`sqlite-adapter-unavailable` or `sqlite-integrity-failed`. Do not paste native
+build logs, private local paths, raw stderr, tokens, license keys or customer data
+into support issues.
+
+## Child signal, timeout and spawn diagnostics
+
+Postinstall child diagnostics include only these safe fields: tool, phase,
+status, reason code, numeric code or `null`, signal or `null`, timeout flag,
+retry attempt, optional timeout metadata and sanitized error code. Raw child
+stdout/stderr is intentionally excluded from diagnostic helpers.
+
+### Public reason-code reference
+
+Use these codes in issues, release notes and support handoffs instead of raw
+terminal output:
+
+| Reason code | Symptom summary | Safe next action |
+| --- | --- | --- |
+| `P177_CHILD_SIGNAL` | A mandatory first-party child closed with a signal such as `SIGINT`. | Retry from a fresh user-owned shell; keep the bounded `signal` field and omit child output. |
+| `P177_CHILD_TIMEOUT` | A mandatory first-party child exceeded its bounded timeout. | Retry once after checking local shell health; attach only `timeoutMs`, `timedOut=true` and the public code. |
+| `P177_PARENT_INTERRUPTED` | The npm lifecycle parent received an interruption and cleaned up a live child. | Confirm whether the user or terminal interrupted the install, then rerun without elevated `HOME`. |
+| `P177_OPTIONAL_TOOL_SIGNAL` | An explicitly opted-in optional tool child closed with a signal. | Treat optional tool setup as fail-open; install or troubleshoot that tool manually outside Neocortex. |
+| `P177_OPTIONAL_TOOL_TIMEOUT` | An explicitly opted-in optional tool child timed out. | Skip optional setup for the Neocortex install and continue with manual vendor setup later. |
+| `P177_OPTIONAL_TOOL_SKIPPED_CI` | CI/non-interactive install skipped optional third-party setup. | No action required for Neocortex install; this is expected in CI. |
+| `P177_OPTIONAL_TOOL_SKIPPED_NONINTERACTIVE` | Non-interactive install skipped optional third-party setup. | Run manual vendor setup separately only if the user wants the optional tool. |
+| `P177_OPTIONAL_TOOL_OPT_IN_REQUIRED` | CodeRabbit or a similar tool is not installed by default. | Follow `docs/install/coderabbit-manual-setup.md` outside the npm lifecycle. |
+| `P177_ROOT_HOME_DETECTED` | Linux root/sudo context may write user config under an elevated account. | Stop using sudo-first install; move to a Node version manager or npm user prefix and use synthetic recovery steps. |
+| `P177_PUBLIC_SAFE_LOG_REDACTED` | Raw child/vendor output or local paths were intentionally omitted. | Share the reason code and bounded fields only; do not paste raw logs. |
+| `sqlite-adapter-unavailable` | Enterprise continuity SQLite adapter is not installed or cannot be loaded. | Reinstall with optional dependencies or install `better-sqlite3` for the client workspace; keep only bounded reason-code evidence. |
+| `sqlite-integrity-failed` | Continuity SQLite integrity/corruption check failed. | Stop durable mutation and use future doctor/repair guidance with public-safe backup/audit evidence only. |
+
+### Sanitized SIGINT/lifecycle troubleshooting
+
+For a sanitized SIGINT npm lifecycle interruption or timeout after optional tool
+status text:
+
+1. Retry in a fresh non-sudo shell.
+2. Prefer a Node version manager or npm user prefix for global installs.
+3. Treat CodeRabbit output as optional/manual unless a user explicitly opted into
+   third-party setup outside the Neocortex npm lifecycle.
+4. If the summary includes `P177_CHILD_SIGNAL`, `P177_CHILD_TIMEOUT` or
+   `P177_PARENT_INTERRUPTED`, keep only the bounded `code`, `signal`, `timedOut`,
+   `timeoutMs` and retry metadata.
+5. If the summary includes `P177_OPTIONAL_TOOL_SIGNAL` or
+   `P177_OPTIONAL_TOOL_TIMEOUT`, continue the Neocortex install and handle the
+   optional tool manually later.
+6. If the summary includes `P177_ROOT_HOME_DETECTED`, follow the no-sudo recovery
+   guide with placeholders such as `<root-home>` and `<user-home>`.
+
+## Root HOME warning
+
+Linux root/sudo contexts emit `P177_ROOT_HOME_DETECTED` when the install may write
+user/global config under an elevated account. The warning uses synthetic path
+examples only; see `docs/install/linux-global-install.md` for recovery guidance.
+
+## Traceability
+
+| Requirement | Contract | Validation |
+| --- | --- | --- |
+| `P177-REQ-05` | `P177-CON-DIAG-01`, `P177-CON-INSTALLER-01`, `P177-CON-OPT-01` | `P177-VAL-05` / `[P177-EV-DIAGNOSTICS]` |
+| `P177-REQ-07` | `P177-CON-CLI-01`, `P177-CON-OPT-01`, `P177-CON-DIAG-01` | `P177-VAL-07` / `[P177-EV-DOCS]` |

package/docs/install/linux-global-install.md

@@ -0,0 +1,97 @@
+# Linux global install without sudo
+
+Story: `P177.03`
+
+Evidence placeholder: `[P177-EV-NOSUDO]`
+
+This guide explains the public-safe Linux install path for Neocortex global npm
+installs. It intentionally uses synthetic paths and placeholders only.
+
+Public npm guidance recommends Node version managers for global-package
+permission issues and lists an npm user prefix as the no-sudo fallback. This
+Neocortex guide follows that order so the default path stays user-owned and does
+not require root `HOME`.
+
+## Preferred install paths
+
+Prefer a Node version manager first. npm documents this as the recommended way to
+avoid global-package permission errors because Node and npm are installed under a
+user-owned location.
+
+```bash
+npm install -g @ornexus/neocortex
+```
+
+If a Node version manager is not available, configure an npm user prefix before
+installing globally:
+
+```bash
+npm config set prefix ~/.local
+export PATH="$HOME/.local/bin:$PATH"
+npm install -g @ornexus/neocortex
+```
+
+Persist the `PATH` line in the user's shell profile only after reviewing the
+shell startup files for that account.
+
+## Why sudo-first installs are risky
+
+Avoid starting with elevated installs such as a root shell or `sudo npm install
+-g`. When the installer runs with root `HOME`, Neocortex user-scoped config and
+agent targets can be written below the elevated account instead of the intended
+user. Linux installer paths emit `P177_ROOT_HOME_DETECTED` when they detect a
+root/sudo context before writing user-scoped config or targets.
+
+The warning does not print real usernames or home directories. It summarizes the
+risk and points to no-sudo remediation first.
+
+## Recovery from root-owned Neocortex config
+
+Use reviewable, placeholder-based steps. Replace placeholders after validating
+the source and destination paths for the affected machine.
+
+1. Inspect what exists under the elevated account:
+
+   ```bash
+   sudo ls -ld <root-home>/.neocortex <root-home>/.claude/agents/neocortex
+   ```
+
+2. Back up before changing ownership or copying anything:
+
+   ```bash
+   sudo tar -czf <reviewed-backup-path>/neocortex-root-config.tgz \
+     <root-home>/.neocortex \
+     <root-home>/.claude/agents/neocortex
+   ```
+
+3. Reinstall as the intended user using a Node version manager or npm user
+   prefix. If an existing activation config must be migrated, copy only reviewed
+   files with explicit owner/group placeholders:
+
+   ```bash
+   sudo install -d -m 700 -o <user> -g <group> <user-home>/.neocortex
+   sudo install -m 600 -o <user> -g <group> \
+     <root-home>/.neocortex/config.json \
+     <user-home>/.neocortex/config.json
+   ```
+
+Do not run broad destructive cleanup commands from this guide. Remove or archive
+root-owned files only after a human reviews the backup and confirms the intended
+user install works.
+
+## Troubleshooting quick checks
+
+- `P177_NOSUDO_EACCES_GUIDANCE`: update/install hit an npm permission error;
+  switch to a Node version manager or npm user prefix before retrying.
+- `P177_ROOT_HOME_DETECTED`: Linux root/sudo context was detected; rerun as the
+  intended user or configure that user's npm prefix.
+- `P177_PUBLIC_SAFE_LOG_REDACTED`: installer diagnostics intentionally omitted
+  raw local paths or child output; use the public reason code rather than a raw
+  terminal transcript in support evidence.
+- Windows `USERPROFILE` behavior is not changed by this Linux guidance.
+
+If a sanitized npm lifecycle interruption is reported after optional-tool status
+text, do not assume CodeRabbit or another third-party tool is part of the default
+install. Cross-check `docs/install/installer-diagnostics.md` for
+`P177_CHILD_SIGNAL`, `P177_CHILD_TIMEOUT`, `P177_PARENT_INTERRUPTED` and optional
+tool reason codes, then retry from a fresh user-owned shell.