NeuralShell

Created by The Founder

NeuralShell is a local-first desktop operator shell for coordinating AI-assisted workflows, offline-capable execution (including Ollama), and release-grade trust controls—verification scripts, checksum discipline, and packaged smoke gates—not generic “AI assistant” hype.

It ships as a hardened React + Electron Windows application: a command palette as the control plane, a workbench model, and strict state / IPC contracts on the main process.

Current public build: Windows x64 only. macOS and Linux are planned but not yet available.

Who should read this README

Goal	Where to start
Install and run the app	Install · Beta program
Product story (operators / buyers)	Documentation Canon · CI status · Release confidence · Buyer proof one-pager · Operator Home · Getting Started
Build, test, or cut a release from source	Prerequisites · Quick start · Build · Release flow
Agents / automation / repo metrics	Documentation Canon · npm run repo:metrics

Tip

Source of truth for docs: Documentation Canon. For operator workflows, see Operator Home and Getting Started.

Install

Current stable release: v2.1.42

v2.1.42 is the current Windows x64 published release at tag f55e042. It includes post-v2.1.41 fixes, Command Palette 2.0, and governance docs. Installers are hash-verifiable (SHA256); they are not Authenticode-signed (SmartScreen may warn on first run).

Master note: Current master may be ahead of the published tag with post-release harness stabilization and docs-only delta records. See docs/releases/POST_V2.1.42_MASTER_DELTA.md.

Platform	File	SHA256
Windows x64 installer	NeuralShell.Setup.2.1.42.exe	af231f031d71620a99bd0eed6cac99d98138cbd0a9c098ee8aef0199c01288f1
Windows x64 product ZIP	NeuralShell-Windows-x64-product.zip	18348c9c35c338a5fd597e8902f7726d23c0c21ae43bf998418c34863c1ff5e7

Install and proof docs: docs/DOCS_INSTALLATION.md · docs/releases/v2.1.42_INSTALL_PROOF.md · docs/RELEASE_CONFIDENCE.md

Verify before running:

Get-FileHash ".\NeuralShell.Setup.2.1.42.exe" -Algorithm SHA256
Get-FileHash ".\NeuralShell-Windows-x64-product.zip" -Algorithm SHA256
# Compare against docs/releases/v2.1.42_SHA256SUMS.txt, then run the full verification suite:
.\VERIFY_RELEASE.ps1

LuxGrid is a separate product/repo — not included in NeuralShell releases.

Beta program (live)

• Recruitment: Call for Beta Testers
• Join via forms: Issue Intake
• Tester checklist: BETA_TESTER_CHECKLIST_V2.0-RC-Final.md
• Control tower: Beta Control Tower

Launch and marketing assets

• Public launch page source: docs/index.html
• Site asset bundle: docs/site-assets/asset-manifest.json
• Pricing: landing/pricing.html
• Partners: landing/partners.html
• Press kit: PRESS_KIT_V2.0-RC-Final.md
• Channel submission: CHANNEL_SUBMISSION_PLAYBOOK_V2.0-RC-Final.md

Revenue and growth (maintainers)

Billing, referrals, partners, and related CLI generators live in docs/README_REVENUE_AND_GROWTH.md so this file stays oriented around install, trust, and contribution.

Enterprise compliance

• SOC2 prep output: SOC2_PREP_REPORT.md · collector: node compliance/soc2_collector.cjs (map in CANON)
• Third-party attribution page: public/about.html (generate with node scripts/genAttribution.cjs)

Agent marketplace

• Core agent manifests: agents/core/*/agent.json
• Install and verify from the in-app Settings → Agent Marketplace gallery

Offline local mode (Ollama)

• Walkthrough: docs/GETTING_STARTED_OFFLINE_OLLAMA.md
• Operator Home and extensions: docs/OPERATOR_HOME.md
• Canvas quick ops: docs/CANVAS_QUICK_OPS.md
• When something breaks: docs/TROUBLESHOOTING.md

For maintainers and contributors

Quick verification (CI / PR)

Hosted GitHub Actions may be billing-locked — use local CI instead:

npm run ci:local          # merge gate (~5–15 min) — run before merging
npm run ci:local:quick    # smoke (~1 min)
npm run ci:local:full     # build + test + E2E + packaged diagnostic
npm run ci:local:ship     # full verify:ship (~20–45 min) — before tagging
npm run ci:status         # runner + workflow dashboard

See docs/CI_STATUS.md, docs/ops/LOCAL_CI.md, and docs/RELEASE_CONFIDENCE.md. Reports: validation-artifacts/local-ci/latest.json.

Self-hosted PR gate: release gates (self-hosted) · Full ship proof: automatic on push to master or dispatch Windows Heavy Validation.

Legacy UI sweep (optional):

npm run verify:ui

See release/E2E_CORE_UI_PACK.md and release/VERIFY_UI_AND_QA_MATRIX.md. After a production desktop build, optional packaged smokes: npm run verify:smoke:all.

Prerequisites

• Node.js 22.12.x (see package.json engines).
• Root .npmrc sets engine-strict=true — npm ci fails on the wrong Node version (EBADENGINE). Engines troubleshooting.

Quick start

One-liner (recommended):

nvm use 22.12.0 && npm run setup

Or step by step:

nvm use 22.12.0
npm run setup
npm test
npm start

Self-sell proof (demo + evidence)

npm run proof:self-sell

Artifacts include screenshots/ui_sales_*.png and release/ui-self-sell-proof-report.json.

Build

npm run icons:generate
npm run build

Prepare public site assets and social card:

npm run channel:site:prepare

Release flow

Official determinism baseline (Node 22.12.x):

npm run proof:bundle
node scripts/release_truth_verify.cjs --determinism-only

Standard and strict ship verification:

npm run ship
npm run ship:strict

Tag workflow (GitHub Actions):

1. Ensure master has successful CI, Merge Gate, Release Contract, and Security Gate runs (or your org’s equivalents).
2. Push a version tag that matches package.json version (examples: v2.1.40, v2.2.0-beta.1). Avoid stale placeholder tags in internal notes—the tag drives the release identity.
3. The Release workflow publishes installer, checksums, provenance, and changelog snapshot.

Full operator steps: RUNBOOK_TAG_RELEASE.md

Rollback

1. Identify prior stable tag on Releases.
2. Re-point the update channel to previous artifacts (dist/OMEGA.yml + installer + blockmap) per runbook.
3. Publish a short rollback note if users must act.

Details: RUNBOOK_HOTFIX.md

Troubleshooting (dev and packaged)

• Packaged startup: npm run diagnose:packaged
• Strict packaged smoke: npm run smoke:packaged:strict
• Release metadata freshness: npm run release:verify:fresh and npm run release:verify:fresh:strict
• Offline checksum helper:

.\scripts\verify.ps1 -SelfTest
.\scripts\verify.ps1
.\scripts\verify.ps1 -Installer

• Bypass local pre-push gate once: $env:NEURAL_SKIP_PREPUSH="1"; git push
• Validate links under docs/, installer/, plugins/, beta/, and root *.md: npm run docs:link-check
• Milestone checklist: npm run roadmap:status · quiet: npm run roadmap:status -- --quiet · strict: npm run roadmap:strict
• Quick doc pass: npm run sanity:docs · full doc contracts: npm run gate:docs
• Fragment / anchor checks: GFM slugs; DOCS_LINK_CHECK_NO_ANCHORS=1 disables anchor-only validation if needed.
• Bypass only docs link in pre-push: $env:NEURAL_SKIP_DOCS_LINK_CHECK="1"; git push
• Bypass only roadmap in pre-push: $env:NEURAL_SKIP_ROADMAP_STATUS="1"; git push

Portable mode

• Windows portable guide: PORTABLE_MODE.md

Security gates

• Dependency review on PRs (high severity fails).
• npm audit --audit-level=high in CI.
• Secret scan via Gitleaks.
• CodeQL analysis on master and PRs.

Privacy

• Privacy policy

Community and wiki

• Discord server blueprint
• Wiki index

License

MIT

---

Created by The Founder