# Grok Build for Alembic Resources

All upstream links are pinned to commit `b189869b7755d2b482969acf6c92da3ecfeffd36` so the course does not silently drift.

## Knowledge

- [Grok Build README — architecture, repository layout, and license](https://github.com/xai-org/grok-build/blob/b189869b7755d2b482969acf6c92da3ecfeffd36/README.md)
  Primary map of the TUI, headless/CI mode, ACP surface, Rust crate boundaries, Apache-2.0 first-party license, and third-party notice boundary. Use for lessons 1–2.
- [Headless mode guide](https://github.com/xai-org/grok-build/blob/b189869b7755d2b482969acf6c92da3ecfeffd36/crates/codegen/xai-grok-pager/docs/user-guide/14-headless-mode.md)
  Canonical CLI flags, `streaming-json` JSONL event contract, token-field policy, incomplete-usage rule, prompt-file behavior, and session flags. Use for lessons 3–6.
- [Session management guide](https://github.com/xai-org/grok-build/blob/b189869b7755d2b482969acf6c92da3ecfeffd36/crates/codegen/xai-grok-pager/docs/user-guide/17-sessions.md)
  Canonical multi-file session directory, authoritative `updates.jsonl`, rewind/compaction state, resume/fork, and worktree semantics. Use for lessons 5 and 8.
- [Authentication guide](https://github.com/xai-org/grok-build/blob/b189869b7755d2b482969acf6c92da3ecfeffd36/crates/codegen/xai-grok-pager/docs/user-guide/02-authentication.md)
  Browser login, `~/.grok/auth.json`, `XAI_API_KEY`, device auth, and credential precedence. Use for lessons 5 and 7.
- [Headless streaming implementation](https://github.com/xai-org/grok-build/blob/b189869b7755d2b482969acf6c92da3ecfeffd36/crates/codegen/xai-grok-pager/src/headless.rs)
  Primary source for line-oriented output and the metadata-only terminal event. Use when parser behavior needs source-level confirmation.
- [Headless usage projection](https://github.com/xai-org/grok-build/blob/b189869b7755d2b482969acf6c92da3ecfeffd36/crates/codegen/xai-grok-shell/src/extensions/notification.rs)
  Primary source for uncached input tokens, cache-read tokens, output tokens, and incomplete-usage signaling.
- Local: `packages/factory/src/GrokAgentProvider.ts`
  The real clean-room phase-one provider: command construction, stdin transport, JSONL parsing, usage projection, errors, and fail-closed resume/fork.
- Local: `packages/factory/src/GrokAgentProvider.test.ts`
  Executable contract for escaping, flags, parsed events, incomplete usage, errors, and session limits.
- Local: `packages/factory/src/AgentProvider.ts`
  Factory's narrow provider seam: `PrintCommand`, `AgentProvider`, `ParsedStreamEvent`, usage, and session storage.
- Local: `packages/factory/src/Orchestrator.ts`
  Real stream consumer and result fallback: parsed result, accumulated text deltas, then raw stdout.
- Local: `.factory/run.ts`, `.factory/Dockerfile`, `packages/factory/README.md`
  Production boundary evidence: fixed roster remains Claude/Codex, the image does not install Grok, and `factory.grok()` is explicitly opt-in.

## Wisdom (Operational Sources)

- Live `grok --version`, `grok --help`, and a no-sandbox sentinel run on the operator host.
  The released CLI can move faster than the pinned repository; re-prove flags and stream shape before widening the integration.
- Alembic's independent Proof/Validator gates.
  Use focused tests for the adapter contract, then a real CLI smoke for transport, authentication, streaming, and result assembly.

## Gaps

- No phase-one proof that Grok is installed and authenticated inside `.factory/Dockerfile`; production image wiring remains future work.
- No atomic transfer design yet for Grok's coordinated multi-file session directory.
- Headless `streaming-json` does not provide Factory-compatible tool-call events; richer telemetry may require ACP/stdio research.