@litfamily/litgrok 1.0.0

package/.grok/vendor/scientific-visualization/tests/test_figure_export.py

@@ -0,0 +1,51 @@
+import unittest
+import sys
+from unittest.mock import Mock
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from scripts.figure_export import save_for_journal, save_publication_figure
+
+
+class FigureExportTests(unittest.TestCase):
+    def tearDown(self):
+        plt.close("all")
+
+    def test_publication_export_defaults_to_transparent_tight_high_dpi(self):
+        fig, _ = plt.subplots()
+        fig.savefig = Mock()
+
+        save_publication_figure(fig, "figure", formats=["png", "pdf"])
+
+        png_kwargs = fig.savefig.call_args_list[0].kwargs
+        pdf_kwargs = fig.savefig.call_args_list[1].kwargs
+        self.assertEqual(png_kwargs["bbox_inches"], "tight")
+        self.assertTrue(png_kwargs["transparent"])
+        self.assertEqual(png_kwargs["facecolor"], "none")
+        self.assertGreaterEqual(png_kwargs["dpi"], 600)
+        self.assertGreaterEqual(pdf_kwargs["dpi"], 600)
+
+    def test_journal_export_forces_nontransparent_background(self):
+        fig, _ = plt.subplots()
+        fig.savefig = Mock()
+
+        save_for_journal(fig, "figure", journal="nature", figure_type="combination")
+
+        kwargs = fig.savefig.call_args.kwargs
+        self.assertFalse(kwargs["transparent"])
+        self.assertEqual(kwargs["facecolor"], "white")
+        self.assertEqual(kwargs["bbox_inches"], "tight")
+
+    def test_publication_export_rejects_missing_output_parent(self):
+        fig, _ = plt.subplots()
+        missing_parent = Path("definitely_missing_parent") / "subdir" / "figure"
+
+        with self.assertRaises(FileNotFoundError):
+            save_publication_figure(fig, missing_parent, formats=["png"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/.grok/vendor/scientific-visualization/tests/test_style_presets.py

@@ -0,0 +1,114 @@
+import unittest
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from scripts import style_presets
+
+
+class DummyFont:
+    def __init__(self, name):
+        self.name = name
+
+
+class StylePresetTests(unittest.TestCase):
+    def tearDown(self):
+        mpl.rcdefaults()
+
+    def test_rcparams_uses_safe_font_stack_when_pretendard_and_arial_missing(self):
+        fonts = [DummyFont("DejaVu Sans"), DummyFont("AppleGothic")]
+
+        with patch.object(style_presets.font_manager.fontManager, "ttflist", fonts):
+            style_presets.rcparams()
+
+        self.assertEqual(mpl.rcParams["font.family"], ["sans-serif"])
+        self.assertEqual(mpl.rcParams["font.sans-serif"][:2], ["DejaVu Sans", "AppleGothic"])
+        self.assertEqual(mpl.rcParams["pdf.fonttype"], 42)
+        self.assertEqual(mpl.rcParams["ps.fonttype"], 42)
+        self.assertEqual(mpl.rcParams["svg.fonttype"], "none")
+
+    def test_rcparams_prioritizes_pretendard_then_arial_when_available(self):
+        fonts = [DummyFont("Arial"), DummyFont("Helvetica"), DummyFont("Pretendard"), DummyFont("DejaVu Sans")]
+
+        with patch.object(style_presets.font_manager.fontManager, "ttflist", fonts):
+            style_presets.rcparams()
+
+        self.assertEqual(mpl.rcParams["font.sans-serif"][:2], ["Pretendard", "Arial"])
+
+    def test_rcparams_forces_agent_safe_grid_and_transparent_export_defaults(self):
+        mpl.rcParams["axes.grid"] = True
+        mpl.rcParams["savefig.transparent"] = False
+
+        style_presets.rcparams()
+
+        self.assertFalse(mpl.rcParams["axes.grid"])
+        self.assertEqual(mpl.rcParams["savefig.bbox"], "tight")
+        self.assertTrue(mpl.rcParams["savefig.transparent"])
+
+    def test_configure_for_journal_validates_widths_and_supports_one_half_column(self):
+        style_presets.configure_for_journal("nature", "one_half")
+        width, height = mpl.rcParams["figure.figsize"]
+
+        self.assertAlmostEqual(width, 120 / 25.4, places=3)
+        self.assertLessEqual(height, 170 / 25.4)
+
+        with self.assertRaises(ValueError):
+            style_presets.configure_for_journal("nature", "poster")
+
+    def test_ensure_zero_origin_ticks_keeps_first_tick_at_zero(self):
+        style_presets.rcparams()
+        fig, ax = plt.subplots()
+        ax.plot([0, 1, 2], [0, 50, 100])
+        ax.set_ylim(0, 100)
+
+        style_presets.ensure_zero_origin_ticks(ax, y=True, nbins=5)
+
+        self.assertEqual(ax.get_ylim()[0], 0)
+        self.assertAlmostEqual(ax.get_yticks()[0], 0)
+        self.assertTrue(all(tick >= 0 for tick in ax.get_yticks()))
+        plt.close(fig)
+
+    def test_style_legend_keeps_black_text_for_nature_and_colored_text_when_requested(self):
+        style_presets.rcparams()
+        fig, ax = plt.subplots()
+        line_a, = ax.plot([0, 1], [0, 1], color="#E69F00", label="A")
+        line_b, = ax.plot([0, 1], [1, 0], color="#56B4E9", label="B")
+
+        legend = style_presets.style_legend(ax, color_text=False)
+        self.assertTrue(legend.get_frame_on())
+        self.assertEqual(legend.get_frame().get_alpha(), 1)
+        self.assertTrue(all(text.get_color() == "black" for text in legend.get_texts()))
+
+        legend = style_presets.style_legend(ax, color_text=True)
+        self.assertEqual([text.get_color() for text in legend.get_texts()], [line_a.get_color(), line_b.get_color()])
+        plt.close(fig)
+
+    def test_style_legend_colored_text_supports_bar_patch_handles(self):
+        style_presets.rcparams()
+        fig, ax = plt.subplots()
+        bars = ax.bar([0, 1], [1, 2], color=["#E69F00", "#56B4E9"], label="bars")
+
+        legend = style_presets.style_legend(ax, color_text=True)
+
+        self.assertEqual(legend.get_texts()[0].get_color(), bars.patches[0].get_facecolor())
+        plt.close(fig)
+
+    def test_plot_scatter_only_creates_no_connecting_line_artists(self):
+        style_presets.rcparams()
+        fig, ax = plt.subplots()
+
+        collection = style_presets.plot_scatter_only(ax, [0, 1, 2, 3], [1, 3, 2, 4], label="observations")
+
+        self.assertIn(collection, ax.collections)
+        self.assertEqual(len(ax.lines), 0)
+        self.assertEqual(collection.get_label(), "observations")
+        plt.close(fig)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+## Unreleased
+
+## 1.0.0
+
+- Release `@litfamily/litgrok` while retaining the `litgrok` and `litgrok-ai` executable aliases, native `.grok` paths, and existing ownership receipts.
+- Preserve ownership-checked upgrades and removal, including refusal of modified, foreign, or unsafe files. Keep legacy skill and agent migration support.
+- Align bilingual install and lifecycle references with the scoped package, document local data and support boundaries, and integrate the Ignition vector cover with editable installation commands in the READMEs.
+- Use the selected Ignition B interlocking terminal mark with exact orange/lime/ivory cell colors in installer, help, SessionStart and README output. Preserve plain fallback, custom product labels, session suppression and functional progress colors; retain previous mark fixtures as history.
+- Retain the shared terminal fallback policy, validated SessionStart mark suppression, and request-scoped reader/technical/audit guidance.
+- Keep cover artwork and its generator out of the npm payload; ship the complete native skills, agents, rules, hooks, and vendor resources.
+
+## 0.2.9 (pending) — 2026-09-03
+
+- Add a shared, request-scoped `reader` / `technical` / `audit` communication
+  contract across the project rule, conversational skills, and agent return
+  packets. Reader replies now filter routine execution metadata while material
+  failures remain visible and detailed evidence, ledgers, and handoffs stay
+  intact.
+- Cover the installed communication contract, parent/child projection,
+  protected operational surfaces, and safe payload upgrades. LitGrok continues
+  to label final-response enforcement as advisory because it does not ship a
+  supported host response interceptor.
+
+## 0.2.8 (pending) — 2026-09-02
+
+- Move the scientific-visualization corpus to `.grok/vendor/` so the skill
+  adapter stays a wrapper over the original files.
+- Count vendor license, provenance, and NOTICE companions in family
+  payload-parity so packed skills keep the material they name.
+
+## 0.2.7 (pending) — 2026-09-02
+
+- Repair payload upgrades across the ownership-manifest transition: installs now
+  record a schema-checked `.grok/.litgrok-install-manifest.json` of SHA-256
+  payload hashes, classify files matching recorded hashes as installer-owned,
+  and atomically replace owned files during upgrades. Uninstall removes owned
+  files and the manifest only after payload removal succeeds.
+- Migrate a pristine manifest-free 0.2.5 payload through the bundled seven-file
+  legacy hash snapshot, while malformed manifests and modified or unrecognized
+  files still fail closed before payload writes.
+- Add regression coverage for historical migration, legacy user edits,
+  malformed ownership metadata, and manifest cleanup; enable full-history CI
+  checkout for the historical archive fixture and document the ownership
+  behavior in both READMEs.
+
+## 0.2.6 (pending) — 2026-09-02
+
+- Harden inode-reuse handling across skill-loop state locks and the
+  autoconference/autoresearch output scaffolders: lock reclaim, failed-acquisition
+  cleanup, and release stay bound to descriptor identity, ctime/birthtime, and
+  exact bytes through tombstone checks, while opened output directories are
+  revalidated against full stat identity before publication. Add same-inode race
+  regressions and regenerate the affected canonical manifests so replacements fail
+  closed while authorized rotations remain valid.
+
+## 0.2.5 (pending) — 2026-09-01
+
+- Add the shared stacked LitFamily ASCII wordmark to the installer and lead both
+  READMEs with the version-free wordmark.
+- Add a CI-enforced, manifest-driven version-lockstep guard for all eight release
+  sites, counting both plain and escaped-regex pins.
+- Report model-picker and output-style selection as Grok host limits rather than
+  shipped surfaces: the installer writes no model or style keys, and
+  `grok inspect --json` exposes no `model`, `outputStyles`, or `settings` keys.
+- Add installer-depth coverage for explicit `--yes` consent, non-interactive
+  no-write behavior, host-limit receipts, measured install phases, and isolated
+  plugin validation.
+
+## 0.2.4 (pending) — 2026-08-31
+
+- Ship the Grok plugin manifest, eleven Grok-native agents, and complete reference
+  corpora for `lit-scientific-visualization`, `lit-handoff`, `autoresearch`, and
+  `autoconference` instead of single-entry skill stubs.
+- Remove unsupported durable-goal-runtime claims from `litgoal` and `litwork`, and
+  add packed-payload substance, cross-product parity, and referenced-path checks so
+  installed skills retain the material they name.
+- Refresh the canonical legal attribution metadata without changing the four
+  upstream attributions it records. This candidate has not been published, tagged,
+  or pushed.
+
+## 0.2.3 (pending) — 2026-08-30
+
+- Make the approved plan-file policy visible: `lit-plan` writes
+  `plans/<slug>.md` and the planning turn is blocked until the file has
+  executable checkbox tasks.
+- Port the Grok-native `lsp-setup` skill with its 20 language references and
+  expose it through the installer and `grok inspect --json` catalog.
+- Add the shared install frame and explicit host-owned model-selection notice;
+  this candidate has not been published, tagged, or pushed.
+- Give the foreground review enough bounded time for the shipped four-turn model
+  route while keeping export and model phases separately capped (5 seconds and
+  60 seconds).
+
+## 0.2.2 (pending)
+
+- Keep the unpublished patch sequence explicit: `0.2.1` remains the first pending package version from the port-completion branch, and `0.2.2` is the subsequent pending skill-learning-loop patch. Publish `0.2.1` before `0.2.2`; this changelog does not claim that either version has been published.
+- Add the user-invoked foreground skill learning loop: bounded session export and secret-scrubbed review, pending-only proposals, explicit apply/reject authority, a content-addressed decision ledger, rollback, and a deterministic archive-only curator.
+- Route agent-owned skill writes only to `$HOME/.grok/skills/<name>/` with `metadata: { litgrokAgentGenerated: "true" }`, while refusing packaged, project-payload, unmarked, modified, and symlinked targets. Transcript content remains inert and `autoApply` remains false.
+- Keep `Stop` and `SessionStart` model-free, preserve the existing SessionStart banner as the first line, and surface at most one pending-review line. Foreground review disables child tools, has a 30-second total budget, and fails closed on invalid or no-op proposals.
+- Support the learning loop on macOS and Linux. On Windows, all learning-loop commands fail before subprocess, project learning-state, or user-skill access with `WINDOWS_SKILL_LOOP_UNSUPPORTED`; passive hooks and installation remain available while a native ACL and process-job helper is pending.
+- Correct all eleven hook registrations to resolve commands from the hook configuration directory and normalize equivalent host event-name casing without accepting a different event.
+
+## 0.2.1
+
+- Prepare the 0.2.1 patch release with the manifest-pinned family-canon rule clarification: host-neutral references, schemas, datasets, legal files, focused references, and scripts may be carried byte-for-byte with provenance; contract prose is translated rather than copied verbatim.
+- Carry the canonical frontend corpus and its legal/provenance records with verified aggregate SHA-256 `f6959eeeae02685102df9fbedafb2c437be4d51df8e102f9fcf32298f7674e7d7`, legal-tree SHA-256 `41b8726914b503469cb4f29410f911ccd9d963c63329bf3509e110c5cfafc7ec`, and dataset SHA-256 `a89011236a6ff14e12ec55fccbfab1bbd40ae34614cea5710c022121aa841bb8`. The reference volume is carried from the family canon rather than newly authored LitGrok prose.
+- Add v1beta2 taste support for the `variance`, `motion`, and `density` dials, with schema, validator, query, and import checks.
+- Carry programming, debugging, visual-qa, lit-comprehend, and browser-drive reference material, and deepen the review-work, start-work, and programming entry points with Grok-native routing and evidence contracts.
+- Fresh Task 8 measurements record 426,524 reference-Markdown words and 38,029 SKILL.md words, versus Task 1's 20,042 and 29,088; review-work is 5,190 source / 3,715 target words, start-work is 4,027 / 2,743, programming is 5,225 / 3,881, and the skill spread is 10.16x versus Task 1's 4.4x. These counts describe carried corpus material and operational entry-point depth, not invented filler.
+
+## 0.2.0
+
+- Replace the two-file static package with a full Grok-native payload; `0.2.0` is a minor-version boundary because the installed product and runtime hook surface changed while the package remains pre-1.0.
+- Ship 33 skills and the project rule at `.grok/rules/00-litgrok.md`.
+- Add the bounded `SessionStart` payload announcement and the blocking `PreToolUse` deliverable-hedge guard.
+- Widen the guard's Korean absent-evidence patterns after two isolated A/B evaluations showed that the original phrase list scored real limitation leaks as clean; the output-channel declaration is machine-readable guard metadata, not a claim that contract prose changes model behavior.
+- Add recording-only `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop`, `PreCompact`, and `PostCompact` hooks backed by a package-owned session ledger.
+- Widen the installer to discover, install, verify, and uninstall the whole packaged `.grok/` tree with its existing refusal and idempotency policy.
+- Keep undocumented schemas blocked: LitGrok ships no plugin manifest, plugin-supplied LSP server configuration, or custom agent definition.
+
+## 0.1.2
+
+- Add `npx litgrok-ai install` / `npx litgrok install`.
+- Family-style cover, English and Korean README, LICENSE.
+
+## 0.1.1
+
+- First public candidate: one Grok skill and one project-rule document.
+- Static npm payload only. No host login, plugin, hook, MCP, or TUI claim.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of conduct
+
+Be respectful and specific in issues, reviews, and project discussions. Critique code and evidence rather than people. Welcome questions, explain assumptions, and respect differing experience and communication styles.
+
+Harassment, threats, discrimination, personal attacks, sexualized conduct, and disclosure of another person's private information are unacceptable. Do not publish private messages or credentials in a report.
+
+Maintainers may edit or remove harmful content, close disruptive discussions, or restrict participation. Responses should consider the severity and context; repeated or serious violations may result in exclusion. Maintainers follow the same expectations.
+
+For a concern, use an available private repository reporting channel. If none is displayed, ask for a private maintainer contact using a minimal issue without identifying or sensitive details. No unverified contact address or guaranteed response time is provided. These expectations apply to project spaces and to people representing the project publicly.

package/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing to LitGrok
+
+LitGrok is an independent, dependency-free Node installer and Grok Build payload. Start with a small issue or pull request that explains the observed behavior, expected behavior, and an isolated reproduction. The scoped npm name is a release candidate; use a local checkout for development.
+
+Use Node.js 22, Git, and npm. There is no dependency install or lockfile. Run from the repository root:
+
+```sh
+node --check bin/litgrok.mjs
+node --check test/skills-and-rules.test.mjs
+node .grok/skills/frontend-ui-ux/scripts/verify-canonical-corpus.mjs
+npm run check:version
+npm test
+npm pack --dry-run --json
+```
+
+The suite includes package, installer, ownership, hooks, and static documentation checks. Optional scientific tooling may be unavailable; report its explicit skip or degraded result. A local hook fixture does not establish authenticated Grok behavior. Historical installer tests use Git history, so retain a full checkout when running those tests.
+
+For a behavior change, preserve a failing regression and test the corrected path plus a meaningful refusal case. Exercise installations in a disposable project and HOME with separate TMPDIR and npm cache. Interactive writes require a terminal; CI and no-color modes remain no-write previews even with `--yes`. Never use a real user profile as a fixture. Preserve unrelated settings, changed skills, and unsafe destinations; clean only your own temporary resources.
+
+Keep npm identity separate from executable aliases and ownership IDs. Do not add dependencies, undocumented host surfaces, or an updater to solve a documentation change. Keep vendor bytes, license notices, accepted artwork, and unrelated changes intact. Product versions and release actions require a separate maintainer decision; CI validates only.
+
+In a pull request, state the trigger and resulting behavior, changed scope, checks with results, unresolved limitations, and cleanup. Remove secrets, transcript excerpts, identifying paths, and credentials from reports. See [security](./SECURITY.md), [privacy](./docs/privacy.md), and the [code of conduct](./CODE_OF_CONDUCT.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LitGrok contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.0/docs/assets/cover.webp" width="100%" alt="LitGrok v5 armory cover" /></p>
+
+<h1 align="center">LitGrok</h1>
+<p align="center"><strong>Keep the work lit.</strong></p>
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.0/docs/assets/litgrok-wordmark.svg" width="480" alt="LITGROK display type" /></p>
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.0/docs/assets/litgrok-clay-icon.png" width="160" alt="LitGrok clay mark" /></p>
+
+Make something useful in Grok Build. Leave the checked result and the next step with your project.
+
+[한국어](./README_ko-KR.md) · [Install](#install-in-30-seconds) · [First use](#first-lit-use) · [Reference](./docs/reference.md)
+
+<p align="center">
+<a href="#install-in-30-seconds"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.0/docs/assets/readme/badge-version.svg" alt="1.0.0" /></a>
+<a href="./LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.0/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
+</p>
+
+<p align="center">
+<a href="./docs/reference.md"><img src="./docs/assets/readme/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install-in-30-seconds">Install</a> &nbsp; <a href="./docs/assets/readme/ignition-film.mp4"><img src="./docs/assets/readme/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="./LICENSE"><img src="./docs/assets/readme/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
+</p>
+
+> **A spark has been placed in your hands. Put it to work.**
+>
+> A bug you want fixed. A screen you want built. A project you want to finish.
+>
+> Starting takes a line. When the session changes, the harder part is finding where you left off. LIT guides you through leaving a goal, a plan, a checked result, and a next step with your project.
+>
+> **Leave something the next session can pick up.**
+
+It ships 34 skills, 11 agents, one project rule, and eleven hook registrations. The installer copies the complete payload into your project; Grok Build runs the session and owns model selection.
+
+Package: **@litfamily/litgrok** · Version: **1.0.0** · [MIT](./LICENSE)
+
+The scientific visualization corpus is packaged at `.grok/vendor/scientific-visualization/`; the numeric `045_scientific-visualization` label remains only in license and provenance filenames.
+
+> [!NOTE]
+> Install the scoped package with the registry command below. An absolute local package path is available for an isolated trial. Landing covers and badges ship in the package so they render on npmjs.
+
+## Start with one lit task
+
+Grok Build uses the explicit `/litwork` route for a bounded task. It owns model execution; LitGrok leaves skills, rules, and checked next steps in the project.
+
+| Prompt or route | Effect |
+| --- | --- |
+| `/litwork` | Start the shipped work checklist in Grok Build. |
+| `handoff` or `/lit-handoff` | Carry the checked result and next step into another session. |
+| `/lit-plan` | Write a plan with concrete checks. |
+| `/start-work <approved-plan>` | Execute an approved plan. |
+| `/review-work` | Review a change and its evidence. |
+| `/litresearch` | Run bounded, source-traceable research without overstating evidence. |
+
+## Practical routes and visual cues
+
+In Grok Build, `/litwork` starts the bounded work checklist; `handoff` or `/lit-handoff` carries the checked result and next step; `/lit-plan` records a plan with checks; `/start-work <approved-plan>` executes that plan; `/review-work` inspects the change and its evidence; and `/litresearch` runs bounded, source-traceable research. The expected effect is a resumable, checked project record. The host limit is explicit: Grok Build owns execution and model selection, while LitGrok installs the `.grok` payload; hooks require a trusted Git root and a plain folder may load skills and rules without hooks. These images are static route cues, not proof of live host behavior.
+
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.0/docs/assets/litgrok-ignition-1600.webp" width="48%" alt="LitGrok ignition apparatus" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.0/docs/assets/litgrok-continuity-1600.webp" width="48%" alt="LitGrok continuity apparatus" /></p>
+
+<p align="center"><a href="./docs/assets/readme/ignition-film.mp4"><img src="./docs/assets/readme/ignition-poster.png" width="720" alt="Ignition motion poster" /></a></p>
+
+The poster opens the optional film; this README keeps motion opt-in.
+
+The retained `docs/assets/cover.svg` is the editable, low-bandwidth fallback; the WebP above is the product emphasis export.
+
+## Install in 30 seconds
+
+With Node.js and Grok Build available, use an open interactive terminal in the project you want to try. The primary install uses the scoped package:
+
+```bash
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok install
+```
+
+For an optional isolated trial, set the actual absolute path of the supplied local package, then run these two lines separately:
+
+```bash
+LITGROK_PACK='/absolute/path/to/the-provided-package.tgz'
+npm exec --yes --package "$LITGROK_PACK" -- litgrok install
+```
+
+The default destination is `<project>/.grok/`. Use `--package @litfamily/litgrok@1.0.0` for a pinned install, or add `--user` to install under `~/.grok/`. [Install and upgrade details](./docs/reference.md#install).
+
+Project hooks need a trusted Git project root in Grok Build. A plain folder can still load the installed skills and rules while hooks remain unavailable. For a new disposable project, run `git init` yourself before trusting it; for an existing repository, open Grok Build from its actual root. The installer never runs `git init` or changes trust. In the observed Grok Build 1.0.13 host, `grok --trust inspect --json` accepted the trust-and-inspect route even though `--trust` was omitted from `grok --help`; this is version-specific behavior.
+
+If `CI` or `NO_COLOR` is set, even to an empty value, installation is a no-write preview. So are `--no-color` and non-interactive runs. Check that the installer reports actual writes before continuing.
+
+## First lit use
+
+Open or restart Grok Build at the installed project’s Git root. Review and trust its project hooks with `/hooks-trust`, or, on the observed Grok Build 1.0.13 host, use `grok --trust inspect --json`. A plain folder can still load skills and rules while hooks remain unavailable. Check `/skills` for the installed catalog and `/hooks` for hook registrations. LitGrok does not create a Git root or change trust.
+
+Start with a small task that needs no external service or existing test suite. Send this in Grok Build:
+
+```text
+/litwork Build a to-do list in one index.html with no external dependencies. Implement add, complete, and delete. Leave the checks performed and the next step. Do not open a browser automatically; give me the steps to check it myself.
+```
+
+Open the generated `index.html` yourself and try adding, completing, and deleting an item. Creating a file and checking its behavior are separate steps. Leave any unrun checks marked unverified; report actual errors back to the session.
+
+### Carry the spark into the next session
+
+```text
+Plan → Build → Verify → Hand off
+```
+
+For a larger change, start with `/lit-plan`, review the saved plan, then invoke `/start-work <plan path>`. Before stopping, ask:
+
+```text
+/lit-handoff Record what we built, what we checked, and what remains. Tell me where you saved the handoff.
+```
+
+In the next session, supply that returned path and ask Grok Build to read it and check the current files before continuing. The default is `.handoff/HANDOFF.md` in a new Git project or `HANDOFF.md` in a non-Git workspace. An existing root handoff is reused. [Destination and handoff guidance](./.grok/skills/lit-handoff/SKILL.md).
+
+**Keeping the spark means leaving work another session can pick up.** These are skill-guided steps in your session; LitGrok does not schedule background work or continue after the session ends.
+
+## How it fits inside Grok Build
+
+The installer puts files in the project's `.grok/` directory. `/litwork` provides a checklist for the current session; Grok Build owns execution and model selection. These are the main connections.
+
+```mermaid
+flowchart TD
+    I["litgrok install"] --> P["Project .grok/ files"]
+    P --> S["skills · /litwork"]
+    P --> R["rules · project guidance"]
+    P --> H["hooks · /hooks-trust required"]
+    S --> G["Grok Build session"]
+    R --> G
+    G -->|Trusted hook events| H
+    H --> L["session-ledger · event chronology"]
+    G -->|Check work · /lit-handoff| N["Project working notes and handoff"]
+    N -.->|User supplies the path| G
+```
+
+The hooks' `.grok/litgrok/session-ledger/` records event order. Judge success from the artifact and its checks. The user supplies the handoff path in the next session; having a record does not automatically resume work.
+
+[Checklist and hook boundaries](./.grok/skills/litwork/SKILL.md) · [Handoff destinations](./.grok/skills/lit-handoff/SKILL.md) · [Install details](./docs/reference.md#install)
+
+## Core routes
+
+| Need | Skill |
+|---|---|
+| Clarify a vague request | [`/deep-interview`](./.grok/skills/deep-interview/SKILL.md) |
+| Write a plan with concrete checks | [`/lit-plan`](./.grok/skills/lit-plan/SKILL.md) |
+| Execute an approved plan | [`/start-work`](./.grok/skills/start-work/SKILL.md) |
+| Keep one task bounded and verifiable | [`/litwork`](./.grok/skills/litwork/SKILL.md) |
+| Review a change and its evidence | [`/review-work`](./.grok/skills/review-work/SKILL.md) |
+| Leave a resumable handoff | [`/lit-handoff`](./.grok/skills/lit-handoff/SKILL.md) |
+
+Use `/skills` for all 34 skills. [Rename compatibility](./docs/reference.md#skill-rename-compatibility) covers the one-release aliases; old slash routes are not guaranteed.
+
+## Safety and uninstall
+
+Preview the exact destinations before writing:
+
+```bash
+npm exec --yes --package "$LITGROK_PACK" -- litgrok install --dry-run
+```
+
+The installer verifies file ownership before upgrades or removal. Modified, foreign, or unsafe destination files cause the operation to refuse rather than overwrite them. `CI`, `NO_COLOR` (even empty), `--no-color`, and non-interactive runs are no-write previews, including with `--yes`.
+
+For a local-package install, remove it with the same package in the same project. Add `--user` only to remove an installation made with `--user`.
+
+```bash
+npm exec --yes --package "$LITGROK_PACK" -- litgrok uninstall
+```
+
+Registry uninstall commands:
+
+```bash
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok uninstall
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok uninstall --user
+```
+
+Match the scope used for installation. Re-run `install` to update. The installer does not grant hook trust, create a Git root, write login state or API keys, or choose a model. The hedge guard is fail-open on host errors; a passing package test does not prove live Grok behavior. Check `/hooks` and `grok inspect --json` from the repository root in your own session. [Host boundaries and verification](./docs/reference.md#verify).
+
+## Documentation
+
+- [Operational reference](./docs/reference.md): installation, hooks, terminal output, payload checks, and source provenance.
+- [Skill learning loop](./docs/reference.md#skill-learning-loop): proposal review, explicit apply, rollback, and macOS/Linux support. Windows learning-loop commands are unsupported.
+- [Project rule](./.grok/rules/00-litgrok.md) and [skill catalog](./.grok/skills/).
+- [Changelog](./CHANGELOG.md) and [license](./LICENSE).
+
+- [Contributing](./CONTRIBUTING.md), [security](./SECURITY.md), [conduct](./CODE_OF_CONDUCT.md), and [support](./SUPPORT.md).
+- [Privacy and local data](./docs/privacy.md); [migration from the old npm name](./docs/reference.md#npm-package-migration).
+
+## LITFAMILY
+
+![Five armored machines representing LitClaude, LitHermes, LitCodex, LitOpenCode, and LitGrok](./docs/assets/litfamily-machines.png)
+
+An editorial illustration of five armored machines representing the products. Each works independently in its own host; they do not need to be installed together or connected to one another.
+
+## LIT mark
+
+<p align="center"><img src="./docs/assets/readme/ascii-readme.svg" width="480" alt="LIT ASCII B mark — Grok" /></p>
+
+<details>
+<summary>Copy ASCII logo</summary>
+
+```text
+                             ▄▄▄▄
+                   ▗███▌   ▗██████▖
+ ▗▄▄▄▄▄          ▗▟████▌   ▝██████▘
+ ▐█████        ▗▟██████▌    ▝▀▜█▀▘
+ ▐█████      ▗▟███████▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
+ ▐█████    ▗▟█████████████████████████ ▐█▀
+ ▐█████    ████████████████████████████▀
+ ▐█████    ██▛▘   ▄ ▄▄▄▄▖▄▄▄▄▄▄▄▄▄▄▄▄▄▖
+ ▐█████    ▀    ▄██ ████▌█████████████▌
+ ▐█████       ▄████ ████▌█████████████▌
+ ▐█████     ▄█████▛
+ ▐█████  ▗▟█████▀▘       ▄▄▄▄▄     ▗▖
+ ▐█████ ▐█████▀          █████     ▐▛▀
+ ▐█████ ▐███▀            █████
+ ▐█████ ▐█▀              █████
+ ▐█████ ▝                █████
+ ▐█████▄▄▄▄▄▄▄▖          █████
+ ▐███████████▛           █████
+ ▐██████████▀            █████
+
+
+grok
+```
+
+</details>
+
+## Ignition motion
+
+Brand motion, not a recording of a Grok task execution.
+
+[![Ignition motion poster](./docs/assets/readme/ignition-poster.png)](./docs/assets/readme/ignition-film.mp4)
+
+[10-second film · MP4](./docs/assets/readme/ignition-film.mp4) · [Animated version · GIF](./docs/assets/readme/ignition-readme.gif)