NeuralShell

NeuralShell is an Electron workstation with strict IPC validation, offline-first defaults, and release provenance gates.

Beta Program (Live)

• Recruitment thread: Call for Beta Testers
• Join via forms: Issue Intake
• Tester checklist: BETA_TESTER_CHECKLIST_v1.2.1-OMEGA.md
• Control tower: Beta Control Tower

Quick Start

1. Install dependencies:

nvm use 22.12.0
npm ci

2. Install local git hooks (recommended):

npm run hooks:install

3. Run tests:

npm test

4. Run app:

npm start

Build

Generate icons first, then package:

npm run icons:generate
npm run build

Release Flow

Standard release verification:

npm run ship

Strict release verification (clean tree + strict packaged smoke):

npm run ship:strict

Tag release workflow (GitHub Actions):

1. Ensure master commit has successful CI, Merge Gate, Release Contract, and Security Gate runs.
2. Push a tag like v1.1.0-OMEGA.
3. Release Tag workflow publishes installer + checksums + provenance + changelog snapshot.

Detailed operator guide: RUNBOOK_TAG_RELEASE.md

Rollback

1. Identify prior stable tag from Releases.
2. Re-point update channel to previous release artifacts (dist/OMEGA.yml + installer + blockmap).
3. If needed, mark current release as superseded and publish rollback note.

Hotfix/rollback guide: RUNBOOK_HOTFIX.md

Troubleshooting

• Packaged startup issues:

npm run diagnose:packaged

• Strict packaged smoke only:

npm run smoke:packaged:strict

• Verify release metadata freshness:

npm run release:verify:fresh
npm run release:verify:fresh:strict

• Offline checksum verification:

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

• Bypass local pre-push gate once:

$env:NEURAL_SKIP_PREPUSH="1"
git push

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.

License

MIT