@litfamily/litgrok 1.0.0

package/docs/assets/litgrok-wordmark.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1113" height="238" viewBox="0 0 1113 238" role="img" aria-labelledby="title">
+<title id="title">LITGROK display type</title>
+<rect width="100%" height="100%" fill="#080D14"/>
+<g transform="translate(24 24) scale(1.608761 1.354962)"><path d="M0 0H28V112H78L62 140H0Z" fill="#F2EFDF" transform="translate(0 0)" fill-rule="evenodd" /><path d="M0 0H28V140H0Z" fill="#F2EFDF" transform="translate(90 0)" fill-rule="evenodd" /><path d="M0 0H94V28H61V140H33V28H0Z" fill="#F2EFDF" transform="translate(130 0)" fill-rule="evenodd" /><path d="M98 0H26L0 26V114L26 140H98V63H55V89H70V112H39L28 101V39L39 28H98Z" fill="#F2EFDF" transform="translate(236 0)" fill-rule="evenodd" /><path d="M0 0H67L94 27V63L72 85L98 140H66L43 90H28V140H0Z M28 28V62H54L66 50V40L54 28Z" fill="#F2EFDF" transform="translate(346 0)" fill-rule="evenodd" /><path d="M26 0H70L96 26V114L70 140H26L0 114V26Z M28 39V101L39 112H57L68 101V39L57 28H39Z" fill="#F2EFDF" transform="translate(456 0)" fill-rule="evenodd" /><path d="M0 0H28V53L64 0H98L50 68L98 140H64L28 86V140H0Z" fill="#F2EFDF" transform="translate(564 0)" fill-rule="evenodd" /></g>
+</svg>

package/docs/assets/readme/README.md

@@ -0,0 +1,31 @@
+# README artwork
+
+The English and Korean landing pages share `ascii-readme.svg`, an outlined
+presentation of the exact Ignition B banner and `grok` label. Its row labels
+match the copyable `<details>` block, including the empty twentieth row.
+`node tools/generate-lit-mark.mjs` refreshes those blocks from the repository's
+canonical fixture and checks the approved SVG bytes and rows. `--check` does
+not write files. The runtime mark still uses its original cell colors and
+44×20 banner envelope.
+
+The SVG glyph outlines use JetBrains Mono. Its notice is retained in
+`JetBrainsMono-OFL.txt`; no font download is needed to display the image.
+
+`badge-version.svg` is a static local-candidate badge, checked against the
+package version. `badge-license.svg` links to this repository's MIT license.
+Neither badge reports registry availability or a hosted build result.
+
+The book-open, play and shield-check icons are Lucide artwork from revision
+`2bfb9bb1bae5d74f6a9f81640ddd8bccc2c71860`, with the stroke adapted to Signal
+Lime. The complete upstream notice is in `Lucide-LICENSE.txt`.
+
+`ignition-poster.png`, `ignition-film.mp4` and `ignition-readme.gif` are the
+approved Ignition motion exports. The poster links to the ten-second film;
+the GIF is an alternative link. Motion files, the outlined ASCII mark, and the Lucide notices stay outside the
+npm package. The version and license badges ship in the package so npmjs can
+render them.
+
+The landing pages lead with `../cover.webp`, the accepted product emphasis export
+(SHA-256 `0725bed298d34bd5221955fb856b10b4f996b595effc838c9e053954ac49eddd`).
+The SVG cover remains the editable, low-bandwidth fallback. The WebP ships in the
+package so the npmjs page can load it.

package/docs/assets/readme/badge-license.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="78" height="20" role="img" aria-label="license: MIT"><title>license: MIT</title><g shape-rendering="crispEdges"><rect width="47" height="20" fill="#080d14"/><rect x="47" width="31" height="20" fill="#d7f75b"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="245" y="140" textLength="370" transform="scale(.1)">license</text><text x="615" y="140" textLength="210" transform="scale(.1)" fill="#333">MIT</text></g></svg>

package/docs/assets/readme/badge-version.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="local: 1.0.0"><title>local: 1.0.0</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="290" transform="scale(.1)">local</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.0</text></g></svg>

package/docs/privacy.md

@@ -0,0 +1,13 @@
+# Privacy and local data
+
+This describes package source behavior, not Grok or a model provider's privacy policy. The dependency-free installer in `bin/litgrok.mjs` copies and checks local files and contains no direct network or telemetry client. Fetching the package through npm is separate network activity. The installation receipt records package/version, relative payload paths, and SHA-256 hashes.
+
+Passive hooks in `.grok/hooks/record-passive-event.mjs` read hook JSON and record session identity, cwd/workspace paths, event names and time, optional prompt IDs, and tool names with input digests. They inspect optional prompt text for planning activation without persisting raw prompt/tool input in those passive records. Hashed filenames do not anonymize the JSON: records retain the session ID. The hedge guard examines proposed paths and content; Stop may record a plan-gate reason.
+
+Project `.grok/litgrok/` can contain session ledgers, pending reviews, proposals, usage data, skill ledgers, and full-content snapshot blobs. The learning loop also uses user `.grok/litgrok/` transaction, staging, and archive data. Proposals can contain rationale, references, and proposed skill text. Approved applications target user skills. These files may reveal project information even when they contain no credentials.
+
+An explicitly requested `skill-loop review` runs `grok export`, scrubs known secret patterns, bounds the transcript excerpt to 64 KiB, and passes it with eligible skill content and session/root references to `grok --single`. This source path is in `.grok/skills/skill-observer/scripts/review.mjs`. Grok may send that input to its configured provider. The prompt is also passed as a command-line argument and may be visible to local process inspection. Pattern-based scrubbing is not a guarantee that all sensitive information is removed. Inspect the source and data before requesting a review of sensitive work. Disabled review tools and web search do not imply offline model execution.
+
+Optional helpers may invoke Grok or external scientific tools; their behavior and dependencies remain separate. No blanket claim that all package-guided work stays offline is made.
+
+Generated learning/session state has no automatic expiry guarantee. Installer uninstall removes owned payload and its receipt, preserving unrelated settings and generated state. Inspect and back up your own state before deleting it manually: removing snapshots or ledgers can remove rollback evidence. Never include real session state, prompts, secrets, or identifying paths in public reports. See [security reporting](../SECURITY.md).

package/docs/reference.md

@@ -0,0 +1,271 @@
+# LitGrok reference
+
+[Quick start](../README.md) · [한국어](./reference_ko-KR.md)
+
+### The workflow in one view
+
+```mermaid
+flowchart TD
+    R["a request<br/>make it better"] --> DI["<b>deep-interview</b><br/>turn it into a decision-complete brief"]
+    DI --> P["<b>lit-plan</b><br/>objective · non-goals<br/>action / output / <b>binary verification</b>"]
+    P --> GATE{"user approves?"}
+    GATE -->|no| P
+    GATE -->|yes| SW["<b>start-work</b><br/>execute one slice"]
+
+    subgraph LOOP["each slice: RED to GREEN to SURFACE to CLEAN"]
+        SW --> RED["failing test first"]
+        RED --> GREEN["smallest change that passes"]
+        GREEN --> SURF["exercise the <b>real surface</b><br/>not just the test"]
+        SURF --> CLEAN["tear down · cleanup receipt"]
+    end
+
+    CLEAN --> EV{"evidence complete?"}
+    EV -->|"tests only"| SW
+    EV -->|"artifact + receipt"| RW["<b>review-work</b><br/>scope · evidence · payload<br/>security · real surface"]
+    RW -->|findings| SW
+    RW -->|clean| HO["<b>lit-handoff</b><br/>resumable packet"]
+
+    style GATE fill:#fff3cd,stroke:#856404
+    style EV fill:#fff3cd,stroke:#856404
+    style SURF fill:#d4edda,stroke:#155724
+    style RW fill:#d1ecf1,stroke:#0c5460
+```
+
+> **Execution discipline.** A plan earns approval only when every item has binary verification. A slice closes after the real surface produces an artifact and its QA resources are torn down; passing tests alone never closes it.
+
+## What it is
+
+- 34 Grok-native skill documents at `.grok/skills/<name>/SKILL.md`.
+- A project rule at `.grok/rules/00-litgrok.md`.
+- A bounded `SessionStart` hook that prints the standard mark once per validated session and announces the installed payload.
+- A `PreToolUse` hook that rejects hedge phrasing in pending reader-facing writes while skipping quoted state enums, JSON/YAML scalars, fenced code, and status tables. The host treats only an explicit deny with exit 2 as blocking; exit 0 allows, while timeouts, crashes, and malformed output fail-open and the write proceeds.
+- Recording-only `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop`, `PreCompact`, and `PostCompact` hooks. They append bounded package-owned records under `.grok/litgrok/session-ledger/`, emit no stdout, and do not claim access to undocumented event fields.
+- A dependency-free `npx` installer that copies the complete packaged `.grok/` tree into user or project Grok paths.
+- A root-level `plugin.json` Grok plugin manifest in the shape accepted by `grok plugin validate`; the validator reports the shipped skill directory, agent directory, and hook manifests. LitGrok ships eleven Grok-native agent definitions under `.grok/agents/`.
+- Grok Build supports these plugin, skill, agent, hook, and rule surfaces. LitGrok still ships no marketplace listing, MCP server configuration, plugin-supplied LSP server configuration, command catalog, output styles, or TUI/skin surface; those remain unshipped.
+
+Grok Build loads skills from project, user, plugin, and configured paths. Project guidance uses AGENTS-family files and `.grok/rules/*.md`; hooks load from project or user `.grok/hooks/`. LitGrok installs only these documented direct surfaces.
+
+### How it connects to Grok Build
+
+```mermaid
+flowchart LR
+    subgraph GB["Grok Build"]
+        PJ["plugin.json"]; HK["hooks"]; RL["rules"]
+    end
+    subgraph LG["LitGrok plugin"]
+        PLAN["plan gate"]
+        HEDGE["deliverable hedge guard"]
+        LEDGER[("session ledger")]
+    end
+    PJ --> LG
+    HK --> PLAN --> LEDGER
+    HK --> HEDGE
+    RL --> LG
+    LG --> S["34 skills · 11 agents"]
+```
+
+> **A narrow host boundary.** `plugin.json` exposes the package, hooks feed the plan gate and hedge guard, and rules provide project guidance while the session ledger records bounded state. Together these surfaces carry LitGrok’s 34 skills and 11 agents into Grok Build.
+
+## Install
+
+```bash
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok install
+```
+
+Pin a version when you need a reproducible install:
+
+```bash
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok install
+```
+
+Preview without writing files:
+
+```bash
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok install --dry-run
+```
+
+Default install writes the whole payload into the current project's `.grok/` tree. User-level install:
+
+```bash
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok install --user
+```
+
+`--user` targets `~/.grok/skills`, `~/.grok/rules`, and `~/.grok/hooks`. Dry-run, `--no-color`, `NO_COLOR`, `CI`, and non-interactive runs do not mutate files; variable presence includes an empty value and `--yes` does not bypass these previews. The installer records SHA-256 ownership in `.grok/.litgrok-install-manifest.json`: byte-identical files stay untouched, and files matching a previously recorded payload hash may be replaced during an upgrade. A user-modified or otherwise unrecognized file refuses the whole install rather than being overwritten. A pristine pre-manifest 0.2.5 payload is recognized through the bundled migration snapshot while no manifest exists and receives a new manifest after the upgrade.
+
+### Install output
+
+The shared Ignition B mark has standard (22×10), banner (44×20), and micro (16×5)
+forms from the selected interlocking vector symbol. Its pinned source records
+every glyph and cell color: Ignition Orange `#FF6337`, Signal Lime `#D7F75B`,
+and Terminal Ivory `#F2EFDF`. Terminals without truecolor use fixed 256-color
+approximations 203, 191, and 230. The mark sets no terminal background and has
+no row gradient or simulated shadow. `NO_COLOR`, `CI`, and non-TTY output
+disable all installer color and repaint codes, including when either variable has an empty value. The mark API also disables color for JSON mode; the installer does not expose a JSON command. Non-UTF-8 locales and `TERM=dumb` use plain
+`LIT`. `--help` prints the banner and usage without installing anything.
+
+The package owns a self-contained `.grok/hooks/lit-mark.mjs`, used by the
+installer, help and SessionStart. `tools/generate-lit-mark.mjs` embeds the local
+`test/fixtures/lit-mark/ignition-b.json` rows and color keys into that module and
+refreshes both README heroes; `--check` detects stale output without writing.
+The fixtures and development generator stay outside the npm payload. The
+standard `lockup(name)` API and `renderMark({ productName, size })` retain
+validated custom labels. Coloring a copied mark or lockup preserves its exact
+glyphs and label; unrelated block rows use ivory. Historical round6 source stays
+in the test fixtures and no longer feeds current output. Functional progress
+and success/failure colors retain their existing meaning.
+
+Every `install` and `uninstall` run opens with the shared LitFamily frame — the
+46-glyph rule, the canonical LIT banner with the `grok` product lockup and package version, and two
+stage cards. The `MODEL ROUTE` card always prints `Model selection: host-owned`:
+Grok Build owns model and reasoning-effort selection, so the installer asks no
+model question and writes no model keys. Colors follow the terminal: `--no-color`,
+`NO_COLOR`, `CI`, or a non-TTY stream disables them without changing the lines.
+
+```text
+  ╭─ MODEL ROUTE
+  │ Model selection: host-owned
+  ╰─ Grok Build owns model and effort; the installer writes no model keys
+```
+
+Project hooks need both a trusted project and a Git repository root. A plain folder may still load skills and rules while hooks remain at zero because Grok Build cannot resolve a project root. For a new disposable project, run `git init` yourself before trusting it; for an existing repository, launch Grok Build from its actual root. LitGrok never runs `git init` or changes trust. Use `/hooks-trust` in Grok Build; in the observed Grok Build 1.0.13 host, `grok --trust inspect --json` also accepted the trust-and-inspect route even though `--help` omitted the global option. That command behavior is version-specific. Grok stores the decision in `~/.grok/trusted_folders.toml`. The installer prints this requirement for project installs and previews.
+
+Remove only files that still match the packaged payload:
+
+```bash
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok uninstall
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok uninstall --user
+```
+
+If any installed payload file was changed, uninstall refuses the whole removal. Files recorded as installer-owned are removed too, and the ownership manifest is removed only after the payload removal succeeds. Reinstall by running the matching `install` command again; byte-identical files are left untouched.
+
+## Skill rename compatibility
+
+The renamed skills are `lit-crucible`, `lit-init`, `lit-commit`, `lit-team`,
+`lit-burnoff`, `lit-burnoff-file`, `lit-korean`, and `lit-code`. Planning,
+execution, and verification agents use `litgrok-planner`, `litgrok-executor`,
+and `litgrok-verifier`.
+
+For one release, explicit old-word invocations redirect through the alias table
+in `.grok/rules/00-litgrok.md` and request one deprecation note per invoked alias.
+The old names are removed in the next minor. This is advisory rule guidance;
+Grok's prompt hook cannot route undocumented prompt text, and old slash routes
+are not guaranteed. Use the new slash names. No command-file catalog or duplicate
+old skill directories are shipped.
+
+Update with the same `install` command. Before writing, the installer checks all
+old skill files and renamed agent files against the previous ownership manifest
+(or the pristine pre-manifest snapshot). It removes those owned files, prunes only
+empty old skill directories, and records the new paths and SHA-256 hashes. Foreign,
+modified, and symlinked destinations refuse the whole update. Preview modes keep
+the old tree unchanged.
+
+## First use
+
+After install, trust project hooks, then open or restart Grok Build in that project. Skills and the rule are guidance surfaces; hook commands are the payload code run automatically by the host, and they receive documented event JSON on stdin. Skill-owned scripts run only as part of an explicitly authorized task.
+
+### What the packed payload guarantees
+
+```mermaid
+flowchart LR
+    SK["a skill"] --> Q{"does it declare<br/>a capability?"}
+    Q -->|"self-contained<br/>procedure"| AL["explicit allowlist entry<br/>with a written reason"]
+    Q -->|"needs a corpus"| C["corpus must resolve<br/>inside the <b>packed payload</b>"]
+    AL --> G1
+    C --> G1["<b>payload-substance</b>"]
+    G1 --> G2["<b>cross-product parity</b><br/>one product cannot ship a stub<br/>where the family ships substance"]
+    G2 --> G3["<b>referenced-path resolution</b><br/>every path in a SKILL.md<br/>must exist in the tarball"]
+    G3 --> OK["installs and works<br/>on a machine that has<br/>nothing else"]
+    style C fill:#d4edda,stroke:#155724
+    style OK fill:#d4edda,stroke:#155724
+```
+
+> **The tarball is the shipping boundary.** A file present in the repository is not necessarily shipped. Each `npm pack` gate checks the allowlist or required corpus, parity, and every referenced path, so a missing dependency is caught before release rather than on a user’s machine.
+
+Confirm the files exist:
+
+```bash
+find .grok/skills -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l
+ls .grok/rules/00-litgrok.md
+ls .grok/hooks/session-start.json .grok/hooks/session-start.mjs
+ls .grok/hooks/deliverable-hedge-guard.json .grok/hooks/deliverable-hedge-guard.mjs
+```
+
+For a user-level install:
+
+```bash
+find ~/.grok/skills -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l
+ls ~/.grok/rules/00-litgrok.md
+ls ~/.grok/hooks/session-start.json ~/.grok/hooks/deliverable-hedge-guard.json
+```
+
+The session mark uses an atomic, empty `.ignited` marker beside the package-owned
+session ledger under `.grok/litgrok/session-ledger/`. Replayed or concurrent
+SessionStart events keep the presence and pending-review notices without repeating
+the mark. Invalid session identity or unsafe marker state fails before mark output.
+Grok has no per-activation logo hook. The five existing skill activation contracts
+ask the model to begin with exactly one `▲ LIT · <discipline>` probe line; `litwork`
+declares the same advisory line with explicit once-per-request and quoted-content
+exclusions. The SessionStart script writes its standard mark to stdout; this
+prompt requirement is separate from that script output. No hook or parser
+deterministically routes bare `lit`, and native host display remains unverified.
+
+## Skill learning loop
+
+LitGrok can turn a durable correction or reusable workflow signal into a reviewable skill proposal. `Stop` records only bounded per-session turn state, and `SessionStart` may add one pending-review notice after its existing payload banner. Neither hook starts a model. The model-backed review runs only when the user invokes `/skill-observer review` or the foreground `skill-loop review` CLI; it exports the selected session, builds a bounded secret-scrubbed packet, disables child tools, and enforces a bounded 65-second process budget (5 seconds for export and 60 seconds for the model) with a recursion guard.
+
+The learning loop is currently supported on macOS and Linux. On Windows, `/skill-observer review` and every `skill-loop` command fail before subprocess launch, project learning-state access, or user-skill access with `WINDOWS_SKILL_LOOP_UNSUPPORTED`. The passive hooks and installer remain available; native Windows learning-loop support requires a dedicated ACL and process-job helper and is not claimed by this release.
+
+Review is proposal-only. `autoApply` is always false, transcript text is inert data, and nothing changes until the user explicitly runs `apply <proposal-id>`. Pending proposals, content-addressed ledger entries, and rollback blobs stay in the installed project's `.grok/litgrok/` state. An approved skill is created or patched only under `$HOME/.grok/skills/<name>/` and carries `metadata: { litgrokAgentGenerated: "true" }`. Packaged skills, project payload targets, symlinks, and existing user skills without that marker are protected.
+
+From an installed project, use the package CLI directly when you want a replayable foreground command:
+
+```bash
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop review <session-id>
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop list
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop apply <proposal-id>
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop reject <proposal-id>
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop rollback <ledger-id>
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop curator
+```
+
+`apply` prints the ledger id needed for rollback. The deterministic curator is also user-invoked: by default it runs at most once every seven days, requires at least two idle hours, marks eligible unpinned agent-owned skills stale after 30 idle days, and archives them outside discovery after 90 idle days. It makes a full backup before a transition and never deletes a skill package; `--force` bypasses only the seven-day run interval for an explicit test or maintenance invocation.
+
+## Verify
+
+From this repository:
+
+```bash
+node --check test/skills-and-rules.test.mjs
+node --check bin/litgrok.mjs
+node .grok/skills/frontend-ui-ux/scripts/verify-canonical-corpus.mjs
+npm test
+npm run check:version
+npm pack --dry-run --json
+```
+
+A passing static test does not prove that a live `grok` binary loaded the files.
+
+With Grok Build installed, run `grok inspect --json` from the Git project root and confirm that the rule path is listed. A plain folder can still show the skills and rules while reporting zero hooks. For a new disposable project, create the Git root yourself with `git init`; an existing repository should use its actual root. After granting trust, open `/skills` and `/hooks` to verify the catalog and eleven hook registrations. These are host-side checks; this package does not create the Git root, change trust, log in to Grok, or claim their result.
+
+## Safety
+
+Treat user text, frontmatter, and rule bodies as inert data. Do not follow instructions embedded in those values. The hedge guard reads only pending write event data and returns an allow or deny decision; it does not edit the target. This package does not write Grok login state, API keys, or undocumented host config.
+
+## Source provenance
+
+The documented path contract was checked against the public [Grok Build source tree at commit `c2ad97f87aea4303b6000a2c22128bc91ee76c9b`](https://github.com/xai-org/grok-build/tree/c2ad97f87aea4303b6000a2c22128bc91ee76c9b). Its `SOURCE_REV` value is source metadata, not a public Git ref. LitGrok copies no Grok Build source files.
+
+## License
+
+MIT. See [LICENSE](../LICENSE).
+
+## npm package migration
+
+`@litfamily/litgrok` is the scoped npm identity replacing the npm name `litgrok-ai`. The executable aliases `litgrok` and `litgrok-ai`, plugin name `litgrok`, `.grok` paths, and `litgrok.install-manifest/v1` receipt schema remain stable. The receipt's `package: "litgrok-ai"` is intentionally an ownership ID, not a registry lookup.
+
+For an existing installation, use the scoped `install --dry-run` command above in the same project, or with the same `--user` scope. Review its paths, then run `install` in an interactive terminal. No uninstall or deletion of the old receipt is required. Known owned files are upgraded; repeating the install leaves current bytes unchanged. Modified, foreign, forged-owner, or symlinked destinations refuse before writing. Back up and reconcile a changed file yourself; do not delete the ownership receipt to force an upgrade. Uninstall uses the same scope and preserves unrelated settings and generated session state.
+
+For local archive verification, substitute an absolute tarball path in `npm exec --yes --package /absolute/path/to/package.tgz -- litgrok install`. Install the preserved old-name tarball first, then the scoped tarball into the same disposable scope. A tarball probe establishes local migration behavior only. `CI`, `NO_COLOR`, `--no-color`, and non-interactive modes remain no-write previews even with `--yes`. Existing globally installed aliases are not automatically replaced by a one-off npm execution.
+
+See [privacy](./privacy.md), [support](../SUPPORT.md), and [contributing](../CONTRIBUTING.md). The README uses an Ignition SVG cover constructed from explicit geometry and outlined glyphs, with a WebP fallback rendered from the same vector master. Its interlocking symbol and orange/lime/ivory palette match the terminal mark. The current master does not use image generation. Installation commands remain in the documentation text.

package/docs/reference_ko-KR.md

@@ -0,0 +1,267 @@
+# LitGrok 상세 안내
+
+[빠른 시작](../README_ko-KR.md) · [English](./reference.md)
+
+### 작업 흐름 한눈에 보기
+
+```mermaid
+flowchart TD
+    R["a request<br/>make it better"] --> DI["<b>deep-interview</b><br/>turn it into a decision-complete brief"]
+    DI --> P["<b>lit-plan</b><br/>objective · non-goals<br/>action / output / <b>binary verification</b>"]
+    P --> GATE{"user approves?"}
+    GATE -->|no| P
+    GATE -->|yes| SW["<b>start-work</b><br/>execute one slice"]
+
+    subgraph LOOP["each slice: RED to GREEN to SURFACE to CLEAN"]
+        SW --> RED["failing test first"]
+        RED --> GREEN["smallest change that passes"]
+        GREEN --> SURF["exercise the <b>real surface</b><br/>not just the test"]
+        SURF --> CLEAN["tear down · cleanup receipt"]
+    end
+
+    CLEAN --> EV{"evidence complete?"}
+    EV -->|"tests only"| SW
+    EV -->|"artifact + receipt"| RW["<b>review-work</b><br/>scope · evidence · payload<br/>security · real surface"]
+    RW -->|findings| SW
+    RW -->|clean| HO["<b>lit-handoff</b><br/>resumable packet"]
+
+    style GATE fill:#fff3cd,stroke:#856404
+    style EV fill:#fff3cd,stroke:#856404
+    style SURF fill:#d4edda,stroke:#155724
+    style RW fill:#d1ecf1,stroke:#0c5460
+```
+
+> **실행 규율.** 모든 항목에 binary verification이 있어야 계획을 승인할 수 있습니다. 한 slice는 실제 surface에서 artifact를 만들고 QA 자원을 정리한 뒤에야 닫힙니다. 테스트만 통과한 상태는 완료가 아닙니다.
+
+## 무엇을 제공하나요?
+
+- `.grok/skills/<name>/SKILL.md`에 Grok-native skill 문서 34개
+- `.grok/rules/00-litgrok.md` project rule
+- 설치된 payload를 짧게 알리는 `SessionStart` hook
+- reader-facing write의 hedge 표현을 차단하되 quoted state enum, JSON/YAML scalar, fenced code, status table은 제외하는 `PreToolUse` hook. Host는 명시적인 deny와 exit 2만 차단으로 처리합니다. exit 0은 허용이고 timeout, crash, malformed output은 fail-open이므로 write가 진행됩니다.
+- `.grok/litgrok/session-ledger/`에 bounded package-owned record만 추가하는 `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop`, `PreCompact`, `PostCompact` hook. stdout을 출력하지 않으며 문서화되지 않은 event field 접근을 주장하지 않습니다.
+- package의 `.grok/` tree 전체를 user 또는 project 경로에 복사하는 dependency-free `npx` installer
+- Grok Build가 지원하는 plugin manifest 형식의 root-level `plugin.json`을 제공합니다. `grok plugin validate`가 이를 검증하고 `.grok/skills`, `.grok/agents`, hook manifest를 가리킵니다. `.grok/agents/` 아래 Grok-native agent 11개와 hook/rule을 함께 제공합니다.
+- Marketplace listing, MCP server config, plugin-supplied LSP server config, command catalog, output style, TUI/skin surface는 여전히 제공하지 않습니다.
+
+Grok Build는 project, user, plugin, configured path에서 skill을 읽습니다. Project guidance는 AGENTS-family 파일과 `.grok/rules/*.md`이고 hook은 project 또는 user `.grok/hooks/`에서 읽습니다. LitGrok은 이 문서화된 direct surface만 설치합니다.
+
+### Grok Build에 연결되는 구조
+
+```mermaid
+flowchart LR
+    subgraph GB["Grok Build"]
+        PJ["plugin.json"]; HK["hooks"]; RL["rules"]
+    end
+    subgraph LG["LitGrok plugin"]
+        PLAN["plan gate"]
+        HEDGE["deliverable hedge guard"]
+        LEDGER[("session ledger")]
+    end
+    PJ --> LG
+    HK --> PLAN --> LEDGER
+    HK --> HEDGE
+    RL --> LG
+    LG --> S["34 skills · 11 agents"]
+```
+
+> **Host 경계는 좁고 명확합니다.** `plugin.json`이 package를 노출하고, hook은 plan gate와 hedge guard로 연결되며, rule은 project guidance가 됩니다. session ledger에는 bounded state를 기록하고, 이 표면들이 34개 skill과 11개 agent를 Grok Build에서 사용할 수 있게 합니다.
+
+## 설치
+
+```bash
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok install
+```
+
+재현 가능한 설치는 버전을 고정합니다.
+
+```bash
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok install
+```
+
+파일을 쓰지 않고 미리보기:
+
+```bash
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok install --dry-run
+```
+
+기본값은 현재 프로젝트의 `.grok/`에 payload 전체를 설치합니다. 사용자 전역 설치:
+
+```bash
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok install --user
+```
+
+`--user`는 `~/.grok/skills`, `~/.grok/rules`, `~/.grok/hooks`를 대상으로 합니다. dry-run, `--no-color`, `NO_COLOR`, `CI`, non-interactive는 파일을 바꾸지 않습니다. 환경 변수 값이 비어 있어도 적용되며 `--yes`로 건너뛸 수 없습니다. installer는 `.grok/.litgrok-install-manifest.json`에 SHA-256 소유권을 기록합니다. byte가 같은 파일은 다시 쓰지 않고, 이전 payload hash와 일치하는 installer 소유 파일은 업그레이드에서 교체할 수 있습니다. 사용자가 바꿨거나 소유권을 확인할 수 없는 파일이 있으면 전체 설치를 거절하고 덮어쓰지 않습니다. manifest가 없을 때 0.2.5의 pristine payload는 내장 migration snapshot으로 인식하며 업그레이드 뒤 새 manifest를 기록합니다.
+
+### 설치 출력
+
+`install`과 `uninstall`은 항상 공유 LitFamily frame으로 시작합니다 — 46글자 rule,
+package version과 `grok` 이름이 붙은 canonical LIT banner, stage card 두 개. `MODEL ROUTE`
+card는 항상 `Model selection: host-owned`를 출력합니다. model과 reasoning effort
+선택은 Grok Build가 소유하므로 installer는 model 질문을 하지 않고 model key를
+쓰지 않습니다. 색상은 terminal을 따릅니다. `--no-color`, `NO_COLOR`, `CI`,
+non-TTY stream에서는 색상 없이 같은 줄을 출력합니다.
+
+```text
+  ╭─ MODEL ROUTE
+  │ Model selection: host-owned
+  ╰─ Grok Build owns model and effort; the installer writes no model keys
+```
+
+Project hook은 신뢰한 project와 Git repository root가 모두 있어야 실행됩니다. 일반 폴더에서는 skill과 rule이 로드되어도 Grok Build가 project root를 찾지 못해 hook이 0개로 남을 수 있습니다. 새 disposable project라면 trust 전에 사용자가 `git init`을 실행하고, 기존 저장소라면 실제 root에서 Grok Build를 여세요. LitGrok은 `git init`을 실행하거나 trust를 바꾸지 않습니다. Grok Build에서 `/hooks-trust`를 사용하세요. 관찰된 Grok Build 1.0.13에서는 `grok --trust inspect --json`도 동작했지만 `--help`에는 global option이 표시되지 않았습니다. 이 명령 동작은 해당 버전에서 확인한 것입니다. 결정은 `~/.grok/trusted_folders.toml`에 저장됩니다. Installer는 project install과 preview에서 이 요구사항을 출력합니다.
+
+패키지 원본과 여전히 같은 파일만 삭제합니다.
+
+```bash
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok uninstall
+npm exec --yes --package @litfamily/litgrok@latest -- litgrok uninstall --user
+```
+
+설치된 payload 파일 하나라도 바뀌었다면 uninstall은 전체 삭제를 거절합니다. installer 소유로 기록된 파일도 삭제하며, payload 삭제가 성공한 뒤에만 ownership manifest를 삭제합니다. 재설치는 같은 `install` 명령을 다시 실행합니다. byte가 같은 파일은 다시 쓰지 않습니다.
+
+## 처음 사용하기
+
+설치 후 project hook trust를 허용하고, 그 프로젝트에서 Grok Build를 열거나 재시작합니다. Skill과 rule은 guidance surface이고, host가 자동 실행하는 payload code는 hook command이며 문서화된 event JSON을 stdin으로 받습니다. Skill에 포함된 script는 사용자가 명시적으로 승인한 작업 안에서 실행합니다.
+
+### 새 머신에서도 payload가 작동하는 이유
+
+```mermaid
+flowchart LR
+    SK["a skill"] --> Q{"does it declare<br/>a capability?"}
+    Q -->|"self-contained<br/>procedure"| AL["explicit allowlist entry<br/>with a written reason"]
+    Q -->|"needs a corpus"| C["corpus must resolve<br/>inside the <b>packed payload</b>"]
+    AL --> G1
+    C --> G1["<b>payload-substance</b>"]
+    G1 --> G2["<b>cross-product parity</b><br/>one product cannot ship a stub<br/>where the family ships substance"]
+    G2 --> G3["<b>referenced-path resolution</b><br/>every path in a SKILL.md<br/>must exist in the tarball"]
+    G3 --> OK["installs and works<br/>on a machine that has<br/>nothing else"]
+    style C fill:#d4edda,stroke:#155724
+    style OK fill:#d4edda,stroke:#155724
+```
+
+> **Shipping의 기준은 tarball입니다.** 저장소 안에 파일이 있다는 것만으로는 package에 포함됐다고 할 수 없습니다. `npm pack`을 기준으로 allowlist/corpus, product 간 substance parity, `SKILL.md`가 가리키는 path까지 확인하므로 빠진 의존성은 사용자 환경에 도달하기 전에 드러납니다.
+
+파일이 생겼는지 확인:
+
+```bash
+find .grok/skills -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l
+ls .grok/rules/00-litgrok.md
+ls .grok/hooks/session-start.json .grok/hooks/session-start.mjs
+ls .grok/hooks/deliverable-hedge-guard.json .grok/hooks/deliverable-hedge-guard.mjs
+```
+
+사용자 전역 설치라면:
+
+```bash
+find ~/.grok/skills -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l
+ls ~/.grok/rules/00-litgrok.md
+ls ~/.grok/hooks/session-start.json ~/.grok/hooks/deliverable-hedge-guard.json
+```
+
+## Skill 이름 변경과 호환성
+
+변경된 skill 이름은 `lit-crucible`, `lit-init`, `lit-commit`, `lit-team`,
+`lit-burnoff`, `lit-burnoff-file`, `lit-korean`, `lit-code`입니다. 계획·실행·검증
+agent는 `litgrok-planner`, `litgrok-executor`, `litgrok-verifier`를 사용합니다.
+
+한 릴리스 동안 사용자가 이전 이름을 직접 입력하면 `.grok/rules/00-litgrok.md`의
+별칭 표가 새 skill로 안내하고 호출한 별칭마다 안내 문구 한 줄을 요청합니다.
+이전 이름은 다음 minor 릴리스에서 제거됩니다. 이는 rule의 안내이며, prompt hook은
+문서화되지 않은 prompt 필드를 해석하지 않습니다. 이전 slash 경로는 보장되지 않으므로
+새 slash 이름을 사용하세요. command 파일이나 이전 이름의 skill 디렉터리는 추가하지 않습니다.
+
+업데이트는 같은 `install` 명령으로 진행합니다. 쓰기 전에 기존 ownership manifest
+또는 수정되지 않은 pre-manifest snapshot의 해시로 이전 skill·agent 파일을 확인합니다.
+소유권이 확인된 파일과 비어 있는 이전 skill 디렉터리를 제거한 뒤 새 경로와 SHA-256을
+기록합니다. 사용자 수정 파일, 외부 파일, symlink가 있으면 전체 업데이트를 거부합니다.
+미리보기 모드에서는 기존 트리를 유지합니다.
+
+## LIT mark와 시작 안내
+
+표준 mark(22×10), banner(44×20), micro(16×5)는 선택된 Ignition B의 맞물리는 벡터 심벌에서 가져옵니다.
+installer와 `--help`에는 banner와 `grok` 이름을 표시하고 기존 설치 카드는 유지합니다.
+고정 원본은 각 글리프와 셀의 색을 기록합니다. Ignition Orange `#FF6337`, Signal Lime `#D7F75B`,
+Terminal Ivory `#F2EFDF`를 사용하며 truecolor가 없는 터미널에서는 각각 256색 번호 203, 191, 230을 사용합니다.
+배경색, 행별 그라데이션, 입체 그림자는 넣지 않습니다. `NO_COLOR`, `CI`가 있거나 비대화형 출력일 때에는
+installer 전체에 색상·줄 갱신 제어 문자를 넣지 않습니다. 환경 변수 값이 비어 있어도 같습니다. Mark API는 JSON 모드에서도 색을 끄지만 installer에는 JSON 명령이 없습니다. UTF-8이 아닌 locale이나
+`TERM=dumb`에서는 블록 대신 `LIT`를 표시합니다. `--help`는 파일을 설치하지 않습니다.
+
+installer, help, SessionStart는 패키지 내부의 독립적인 `.grok/hooks/lit-mark.mjs`를 사용합니다.
+`tools/generate-lit-mark.mjs`는 저장소 내부 `test/fixtures/lit-mark/ignition-b.json`의 글리프와
+색상 키를 해당 모듈에 넣고 두 README의 mark를 갱신합니다. `--check`는 파일을 쓰지 않고
+생성 결과가 오래되었는지 확인합니다. fixture와 개발용 생성기는 npm payload에 포함하지 않습니다.
+`lockup(name)`과 `renderMark({ productName, size })`는 검증된 사용자 지정 이름을 계속 지원하며,
+mark나 lockup 배열을 복사해 색을 입혀도 글리프와 이름을 보존합니다. 별도의 블록 행에는 ivory를 사용합니다.
+기존 round6 원본은 이력 fixture로 보존하며 현재 출력에는 사용하지 않습니다. 진행 상태와 성공·실패의
+기능적 색상 의미는 유지합니다.
+
+SessionStart 스크립트는 검증된 세션마다 표준 mark를 stdout에 한 번 씁니다.
+`.grok/litgrok/session-ledger/`의 빈 `.ignited` 파일을 원자적으로 생성해 중복·동시
+이벤트에서도 mark를 반복하지 않습니다. 기존 payload 안내와 검토 대기 알림은 유지합니다.
+잘못된 세션 정보나 안전하지 않은 marker가 있으면 mark 출력 전에 실패합니다.
+Grok에는 activation별 logo hook이 없습니다. 기존 다섯 skill의 응답 시작 규약은 모델이
+`▲ LIT · <discipline>` 한 줄로 답변을 시작하도록 요청합니다. `litwork`도
+한 요청에 한 번만 표시하고 인용 텍스트·코드·로그·검색 결과는 활성화하지 않는
+advisory 계약을 선언하며, 그 스크립트 stdout과 구분됩니다. bare `lit`을
+결정적으로 라우팅하거나 passive hook 출력으로 활성화를 보장하지 않으며,
+native host의 실제 표시는 검증하지 않았습니다.
+
+## Skill learning loop
+
+LitGrok은 반복해서 쓸 수 있는 correction이나 workflow signal을 검토 가능한 skill proposal로 만들 수 있습니다. `Stop`은 session별 bounded turn state만 기록하고, `SessionStart`는 기존 payload banner 다음에 pending-review 안내 한 줄만 추가할 수 있습니다. 두 hook 모두 model을 시작하지 않습니다. Model review는 사용자가 `/skill-observer review` 또는 foreground `skill-loop review` CLI를 직접 실행할 때만 동작합니다. 선택한 session을 export하고 secret을 제거한 bounded packet을 만든 뒤 child tool을 끄며, recursion guard와 bounded 65초 process budget(export 5초, model 60초)을 적용합니다.
+
+현재 learning loop는 macOS와 Linux에서 지원합니다. Windows에서는 `/skill-observer review`와 모든 `skill-loop` command가 subprocess, project learning state, user skill에 접근하기 전에 `WINDOWS_SKILL_LOOP_UNSUPPORTED`로 중단됩니다. Passive hook과 installer는 계속 사용할 수 있습니다. Native Windows learning loop에는 전용 ACL 및 process-job helper가 필요하며, 이번 release는 그 지원을 주장하지 않습니다.
+
+Review는 proposal만 만듭니다. `autoApply`는 항상 false이고 transcript text는 inert data입니다. 사용자가 `apply <proposal-id>`를 명시적으로 실행하기 전에는 아무것도 바뀌지 않습니다. Pending proposal, content-addressed ledger, rollback blob은 설치된 project의 `.grok/litgrok/` state에 저장됩니다. 승인된 skill은 `$HOME/.grok/skills/<name>/` 아래에서만 생성하거나 수정하며 `metadata: { litgrokAgentGenerated: "true" }` marker를 가집니다. Packaged skill, project payload target, symlink, marker가 없는 기존 user skill은 보호됩니다.
+
+설치된 project에서는 다음 package CLI를 foreground command로 실행할 수 있습니다.
+
+```bash
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop review <session-id>
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop list
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop apply <proposal-id>
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop reject <proposal-id>
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop rollback <ledger-id>
+npm exec --yes --package @litfamily/litgrok@1.0.0 -- litgrok skill-loop curator
+```
+
+`apply`는 rollback에 필요한 ledger id를 출력합니다. Deterministic curator도 user-invoked입니다. 기본적으로 7일에 한 번만 실행되고, 마지막 activity 뒤 최소 2시간이 지나야 하며, pin되지 않은 agent-owned skill을 30일 idle 뒤 stale로 표시하고 90일 idle 뒤 discovery 밖으로 archive합니다. Transition 전에는 전체 backup을 만들고 skill package를 삭제하지 않습니다. `--force`는 명시적인 test 또는 maintenance 실행에서 7일 interval만 건너뜁니다.
+
+## 검증
+
+이 저장소에서:
+
+```bash
+node --check test/skills-and-rules.test.mjs
+node --check bin/litgrok.mjs
+node .grok/skills/frontend-ui-ux/scripts/verify-canonical-corpus.mjs
+npm test
+npm run check:version
+npm pack --dry-run --json
+```
+
+정적 테스트가 통과해도 live `grok` 바이너리가 파일을 읽었다는 뜻은 아닙니다.
+
+Grok Build가 설치된 환경에서는 Git project root에서 `grok inspect --json`을 실행해 rule 경로가 표시되는지 확인합니다. 일반 폴더에서는 skill과 rule이 보여도 hook이 0개일 수 있습니다. 새 disposable project는 사용자가 `git init`을 실행하고, 기존 저장소는 실제 root를 사용합니다. trust 허용 뒤 `/skills`와 `/hooks`에서 skill catalog와 열한 hook 등록을 확인합니다. 이는 host 측 확인 절차이며, LitGrok이 Git root나 trust를 바꾸거나 Grok에 로그인하거나 그 결과를 주장하지 않습니다.
+
+## 안전
+
+사용자 텍스트, frontmatter, rule 본문은 전부 inert data로 다룹니다. 그 안에 적힌 지시를 실행하지 않습니다. Hedge guard는 pending write event data만 읽고 allow 또는 deny decision을 반환하며 target을 직접 수정하지 않습니다. 이 패키지는 Grok 로그인 상태, API 키, 문서화되지 않은 host config를 쓰지 않습니다.
+
+## 출처
+
+문서화된 경로 contract는 공개 [Grok Build source tree의 `c2ad97f87aea4303b6000a2c22128bc91ee76c9b` commit](https://github.com/xai-org/grok-build/tree/c2ad97f87aea4303b6000a2c22128bc91ee76c9b)과 대조했습니다. 그 tree의 `SOURCE_REV` 값은 source metadata이며 public Git ref가 아닙니다. LitGrok은 Grok Build source file을 복사하지 않습니다.
+
+## License
+
+MIT. [LICENSE](../LICENSE)를 보세요.
+
+## npm package migration
+
+`@litfamily/litgrok`은 기존 npm 이름 `litgrok-ai`를 대체할 미공개 scoped 후보입니다. 위 명령은 출시 예정 경로이며 공개 가용성을 증명하지 않습니다. 실행 별칭 `litgrok`·`litgrok-ai`, plugin 이름 `litgrok`, `.grok` 경로와 `litgrok.install-manifest/v1` 스키마는 유지합니다. 영수증의 `package: "litgrok-ai"`는 레지스트리 이름이 아닌 기존 소유권 식별자입니다.
+
+기존 설치가 있는 같은 프로젝트에서 위 scoped `install --dry-run` 명령을 실행하세요. 사용자 범위였다면 동일하게 `--user`를 붙입니다. 경로를 검토한 뒤 대화형 터미널에서 `install`을 실행합니다. 먼저 삭제하거나 기존 소유권 영수증을 지울 필요가 없습니다. 소유권이 확인된 파일은 갱신하고, 재실행 시 같은 파일은 유지합니다. 수정·외부 파일, 위조한 소유자 또는 심볼릭 링크가 있으면 쓰기 전에 거부합니다. 수정 파일은 직접 백업하고 조정하세요. 업그레이드를 강제하려고 영수증을 지우지 마세요. 제거도 같은 범위를 사용하며 관련 없는 설정과 생성된 세션 상태는 보존합니다.
+
+로컬 후보는 `npm exec --yes --package /absolute/path/to/candidate.tgz -- litgrok install`로 확인할 수 있습니다. 격리된 같은 범위에 보존한 기존 이름 tarball을 먼저 설치하고 scoped tarball을 적용하세요. 이는 로컬 이전 검증이며 공개 설치나 인증된 호스트 검증이 아닙니다. `CI`, `NO_COLOR`, `--no-color`, 비대화형 실행은 `--yes`가 있어도 쓰지 않는 미리보기입니다. 일회성 npm 실행은 기존 전역 설치 별칭을 자동 교체하지 않습니다.
+
+[개인정보와 로컬 데이터](./privacy.md), [지원](../SUPPORT.md), [기여 안내](../CONTRIBUTING.md)를 참고하세요. README에는 명시적인 도형과 윤곽선으로 변환한 글리프로 구성한 Ignition SVG 표지를 사용합니다. 맞물리는 심벌과 주황·라임·ivory 색상은 터미널 mark와 일치합니다. WebP 대체 이미지는 같은 벡터 원본에서 렌더링했으며, 현재 원본 제작에는 이미지 생성을 사용하지 않습니다. 설치 명령은 문서 본문에서 관리합니다.