# Contributing

> Required check and package commands, no generated payloads in Git, do not weaken checksum or signing gates, private security reports.

- Repository: sashimikun/grok-bot-0.18-reconstructed
- GitHub: https://github.com/sashimikun/grok-bot-0.18-reconstructed
- Human docs: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15
- Complete Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/llms-full.txt

## Source Files

- `CONTRIBUTING.md`
- `SECURITY.md`
- `NOTICE.md`
- `PROVENANCE.md`
- `package.json`
- `tests/publication-packaging.test.mjs`

---

---
title: "Contributing"
description: "Required check and package commands, no generated payloads in Git, do not weaken checksum or signing gates, private security reports."
---

This repository is a small-club reconstruction. A shareable change must pass `npm ci`, `npm run check`, and `npm run frontend:build`. After `npm run bootstrap` on macOS Apple Silicon, package changes must also pass `npm run package` and `npm run verify`. `check` is `typecheck` (`frontend/tsconfig.json`) plus `source:typecheck` (`source/tsconfig.json`) plus `node --test tests/*.test.mjs`. `package` re-runs `check`, then `scripts/package-macos.mjs`. Node is pinned to `>=26.5.0 <27`. Do not commit generated application payloads or local evidence, and do not weaken checksum, bundle identity, code-signing, or clean-export checks to make a build pass.

<Warning>
This is not a supported production distribution. Do not reuse real credentials or sensitive accounts while experimenting. Report issues privately to the repository owner; do not open a public disclosure against this experimental codebase.
</Warning>

## Required commands

<Steps>
<Step title="Install a clean tree">
Use Node 26.5.x. From the repository root:

```sh
npm ci
```

`postinstall` applies `scripts/apply-third-party-patches.mjs`. Do not skip `npm ci` for a shareable change.
</Step>
<Step title="Run the share gate">
```sh
npm run check
npm run frontend:build
```

`check` fails if frontend TypeScript, reconstructed runtime TypeScript, or any `tests/*.test.mjs` file fails. `frontend:build` is `vite build --config frontend/vite.config.ts` and is required even though the packaged UI still uses the patched shipped renderer by default.
</Step>
<Step title="On macOS, package and verify">
After a successful `npm run bootstrap`:

```sh
npm run package
npm run verify
```

`package` aborts on non-Darwin with `The reconstructed macOS application can only be packaged on macOS.` Output is `dist/Grok Bot 0.18 Reconstructed.app` unless `GROK_BOT_OUTPUT_APP_NAME` overrides the basename. `verify` inspects that bundle (or `--app /absolute/path/to/App.app`), not `.build/app.asar`.
</Step>
</Steps>

<RequestExample>
```sh title="Share a change"
npm ci
npm run check
npm run frontend:build
```
</RequestExample>

<RequestExample>
```sh title="macOS package gate"
npm run bootstrap
npm run package
npm run verify
```
</RequestExample>

Optional extra commands after a packaged app exists: `npm run smoke` (native e2e, 12s timeout) and `npm run publication:check` (archive/init/add tree equality on `HEAD`). Those are not substitutes for `check` / `frontend:build` / `package` / `verify`.

| Script | What it runs | Required before sharing |
| --- | --- | --- |
| `npm run check` | `typecheck` + `source:typecheck` + `test` | Yes |
| `npm run frontend:build` | Vite build of `frontend/` | Yes |
| `npm run package` | `check` then `scripts/package-macos.mjs` | Yes on macOS for packaging changes |
| `npm run verify` | `scripts/verify.mjs` against the selected `.app` | Yes on macOS after `package` |
| `npm test` | `node --test tests/*.test.mjs` | Covered by `check` |
| `npm run smoke` | `scripts/smoke.mjs`, `timeoutMs: 12_000` | Optional native launch check |
| `npm run publication:check` | `scripts/verify-publication-tree.mjs` | Before a public remote / clean export |

## Classify the change

Use focused commits. State which surface moved:

| Surface | Typical paths | Packaged effect |
| --- | --- | --- |
| Reviewed runtime source | `source/` | Compiled into the reconstructed ASAR (`clean-source` runtimes) |
| Editable frontend | `frontend/` | Vite design workspace; default `package` does **not** replace the shipped renderer |
| Checksum-pinned packaged renderer | Hydrated `src/app/dist/renderer` plus `scripts/lib/router-renderer-patch.mjs` | Default UI authority; only a narrow, hash-recorded Router transform is applied |
| Packaging only | `scripts/package-macos.mjs`, `scripts/verify.mjs`, `scripts/lib/codesign.mjs` | Bundle identity, ASAR swap, ad-hoc sign, verify |

Passing `frontend:build` alone does not prove the packaged UI changed. Default packaging calls `buildFidelityReconstructedAsar()` and keeps the checksum-pinned shipped renderer. Override only with an explicit `GROK_BOT_RENDERER_SOURCE` directory that contains `index.html`.

## Keep generated payloads out of Git

The checked-in tree is reconstructed source, tests, manifests, build scripts, and Git LFS original 0.18.0 installers. Bootstrap hydrates ignored `src/app/dist`. Package writes ignored `.build/` and `dist/`.

`.gitignore` (root-anchored) includes:

| Pattern | Why it stays out of Git |
| --- | --- |
| `/.cache/` | Bootstrap DMG / runtime cache |
| `/.build/` | Staged ASAR and package scratch |
| `/dist/` | `Grok Bot 0.18 Reconstructed.app` |
| `/src/app/dist/` | Checksum-pinned hydrated payload |
| `/recovered/` | Root recovery output (not `frontend/src/recovered/`) |
| `/recovery/`, `/reports/`, `/work/` | Local evidence and scratch |
| `/.tmp*/`, `/.grok-*/`, `/.playwright-cli/`, `/.http-probe.*/`, `/.mcp-bridge.*/`, `/.openrouter-probe.*/`, `/.router-*/` | Machine-local harnesses |
| `/host-main.cjs`, `/main.cjs`, `/index-*.js`, `/katex-*.js`, `/mermaid.core-*.js`, `/xlsx-*.js`, `/index.html` | One-off extracted copies at repo root |

`tests/publication-packaging.test.mjs` requires `^/recovered/$` (root only) and that `frontend/src/recovered/ui/sand-form-primitives.css` remains addable. Do not “fix” publication by ignoring `frontend/src/recovered/`.

Before a public remote, `npm run publication:check` archives `HEAD`, `git init`s a fresh tree, `git add --all`, and requires `HEAD^{tree}` to equal the new `write-tree`. Mismatch throws `Fresh publication export changed the tracked tree`. Confirm `git status --ignored` shows no generated payload selected for Git.

## Do not weaken gates

Do not patch these checks to green a PR.

### Checksums

| Pin | Value / owner |
| --- | --- |
| 0.18.0 DMG SHA-256 | `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb` |
| Original `app.asar` SHA-256 | `6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58` |
| Renderer mode | Default packaged renderer is `checksum-pinned-artifact-runtime`; `verify` byte-compares the inventory |

Bootstrap fails on LFS pointer-sized archives and on `checksum mismatch`. `verify` fails if a packaged renderer file’s bytes or SHA-256 drift from provenance, or if `ElectronAsarIntegrity` remains in `Info.plist`.

### Bundle identity

`scripts/lib/config.mjs` sets `reconstructedBundleId` to `com.anysphere.sand.reconstructed` and `reconstructedName` to `Grok Bot 0.18 Reconstructed`. `package` writes those via `plutil` and registers URL scheme `sand` only. `verify` throws `Unexpected reconstructed bundle ID` or `Unexpected reconstructed display name` on drift. Do not restore `com.anysphere.sand` or claim the upstream Developer ID / notarization.

### Code signing

Packaging clears `_CodeSignature`, ad-hoc signs with identity `-` (`--force --deep --timestamp=none --sign -`), retries once on transient nested-framework failure, then runs `codesign --verify --deep --strict`. `verify` repeats that verify. Quarantine is stripped with `xattr -cr` so Gatekeeper does not reject a valid ad-hoc signature. Do not skip sign or verify to paper over a dirty payload.

### Updater and telemetry guard

Reconstructed Electron-main packaging prepends an idempotent guard:

```js
process.env.SAND_DISABLE_UPDATES ??= "1";
process.env.SAND_DISABLE_SENTRY ??= "1";
process.env.SAND_DISABLE_TELEMETRY ??= "1";
```

`tests/reconstructed-updater-guard.test.mjs` locks that prefix. Explicit environment still wins (`??=`). Do not remove the guard to “match production.”

### Clean export and production bindings

Checked-in production bindings must resolve under `source/`. `publication:check` and `git archive` must not drop `frontend/src/recovered`. Do not loosen ignore rules, tree-equality, or binding-path assertions to hide generated evidence.

## Frontend and evidence-only UI

`frontend/` is a partial, evidence-backed reconstruction. Packaged builds keep the pinned renderer and apply only the recorded Settings Router transform unless `GROK_BOT_RENDERER_SOURCE` overrides it.

The immutable 0.18.0 release is the product specification. Recovered source may express only behavior with an inspectable artifact anchor (emitted code or source-path markers, capsules/source maps, shipped strings/assets/CSS, renderer DOM signatures, IPC/RPC contracts, or repeatable observation). Do not invent a screen, route, control, label, selector, state, or interaction to fill a gap. Passing typecheck or Vite build is not provenance. Speculative UI is a release-blocking defect.

`@evidence` comments in `frontend/` are provenance annotations, not imports.

## Security reports

<ParamField body="channel" type="string" required>
Private report to the repository owner. Do not file a public disclosure against this experimental codebase.
</ParamField>

Reconstructed packages default the official updater, Sentry, and upstream telemetry off at the Electron-main packaging boundary. The bootstrap download and hydrated `app.asar` remain checksum-pinned.

`npm audit` still reports compatibility-bound advisories in pinned Electron 42.1, Undici 5 / Connect 1, AI SDK 4, and OpenTelemetry. Patch-level fixes are allowed only when they do not change reconstructed runtime contracts. Do not silently major-upgrade those stacks as publication cleanup.

No upstream source-code license is granted. `NOTICE.md` and `PROVENANCE.md` require an independent rights review before public redistribution. Preserved LFS installers remain under their own terms.

## Local verification signals

<Check>
`npm run check` and `npm run frontend:build` exit 0.
</Check>

<Check>
On macOS, `npm run package` prints `Packaged application: .../dist/Grok Bot 0.18 Reconstructed.app` and `npm run verify` prints `Verified packaged ASAR` plus reconstructed bundle identity and code signature.
</Check>

<Check>
`git status --ignored` does not stage `.cache/`, `.build/`, `dist/`, `src/app/dist/`, or `/recovered/`.
</Check>

Failure strings that mean a gate is working, not a license to skip it:

| Signal | Meaning |
| --- | --- |
| `The reconstructed macOS application can only be packaged on macOS.` | `package` is Darwin-only |
| `Unexpected reconstructed bundle ID` | `CFBundleIdentifier` is not `com.anysphere.sand.reconstructed` |
| `ASAR is missing …` | Required packaged paths dropped |
| `Packaged artifact renderer differs from its checksum inventory` | Renderer bytes drifted |
| `Fresh publication export changed the tracked tree` | Ignore/export rules drifted |
| `checksum mismatch` | Bootstrap pin failed |

## Next

<CardGroup>
<Card title="npm scripts" href="/npm-scripts">
Exact `package.json` commands: `bootstrap`, `check`, `package`, `verify`, `smoke`, `publication:check`, `frontend:build`.
</Card>
<Card title="Package the macOS app" href="/package-macos-app">
Compile runtimes, patch Settings Router, replace `app.asar`, set reconstructed identity, ad-hoc sign, verify.
</Card>
<Card title="Verify and smoke" href="/verify-and-smoke">
Required ASAR paths, evidence markers, native e2e with 12s timeout, `SAND_DISABLE_*` defaults.
</Card>
<Card title="Publication export" href="/publication-export">
`publication:check` tree equality, LFS push of installers, `NOTICE`/rights review.
</Card>
<Card title="Work on the frontend reconstruction" href="/edit-frontend-workspace">
`frontend/` Vite workspace versus the patched shipped renderer.
</Card>
<Card title="Evidence and provenance" href="/evidence-and-provenance">
Pinned 0.18.0 identities, evidence-only UI rule, production bindings into `source/`.
</Card>
</CardGroup>