gitifact 0.6.2 → 0.7.1

package/dist/i18n/en/block.md

@@ -0,0 +1,48 @@
+## Gitifact Guide
+
+gitifact v{version} · {language} · storage schemaVersion 2
+
+CLI: use `npx --yes gitifact@{version} <cmd>` by default. Below, `gitifact` stands for this invocation. Follow the project's instructions if they specify another method, such as a local installation or global command.
+
+### At the start
+
+- A global installation is optional. Version-pinned npx uses a matching project dependency or downloads the package to the npm cache. If execution or downloading is blocked, request the required approval and explain the cause. Do not substitute manual specification saves or commits, or claim completion without running the CLI.
+- Once per new session, run `gitifact update --check` with the pinned version. If the result is `available`, ask whether to update; run the suggested new-version `update` command only with consent. If declined, unavailable, or disabled, continue with the pinned version and do not ask again in that session. After updating, reread the block and use its new version. Commit and push only when separately authorized.
+- Run `gitifact spec working` to read wiki pages, feature specifications, and warnings. Check git status and existing staging.
+- This block is a summary. Read `gitifact docs <topic>` for detailed formats instead of relying on memory.
+
+### What belongs in requirements
+
+Record product behavior and constraints that must be maintained.
+
+| Request | Treatment |
+| --- | --- |
+| Let users delete their posts | Record as a requirement |
+| Rename this internal function | An implementation change |
+| Push now | A work instruction; do not register it |
+| It must work without external services | Record as a product constraint |
+
+### Rules
+
+- Read `gitifact docs spec` before saving specifications. Use only IDs issued by the CLI.
+- For a new feature, prepare requirements.md and design.md together (`gitifact docs design`). Follow a request for requirements only.
+- Before changing requirements, designs, or code, read `gitifact docs wiki` and the relevant wiki pages named by its guidelines.
+- To tailor the wiki guidelines, update `.gitifact/wiki/README.md` through `spec save`. Its contents become the guidelines in `docs wiki`.
+- Before writing wiki, requirements, or design content, follow `gitifact docs writing`. Use the project's language for its documents, independently of the CLI display language.
+- When asked to commit, read `gitifact docs commit` and commit related specifications, reasons, code, and tests together.
+- Automatic recording does not authorize commits. Commit only on user request or under an explicit project policy. Pushing requires separate authorization.
+- Ask only about unclear product behavior and continue independent work. Derive all existing features only when asked.
+- SELF-CHECK: before preparing save or commit input, reread the relevant docs and compare formats. If unsure, run `gitifact docs <topic>` instead of guessing.
+- Write save and commit JSON to the inputs paths returned by `spec working`. The CLI removes the file on success. Do not save query results or docs output to files; rerun them when needed.
+- When the user asks to see requirements, project status, or change history, start `gitifact browser` in the background and share its URL. Do not substitute a chat summary.
+### Commands
+
+- `docs <topic>`: {topics}
+- `spec working`: all current specifications and wiki pages, warnings, stamp, and input paths (`--stamp`, `--feature <name>`, `--ids`)
+- `spec save --file <json|->`: save requirements, designs, and wiki pages
+- `spec commit --file <json|->`: record reasons and commit in one operation
+- `browser`: run the read-only browser server; prints a URL and keeps running
+- `update [--check | --commit]`: `--check` only checks versions. Without it, refresh this block to the running version; `--commit` commits block-only changes with a fixed message
+- `init`: create configuration and this block when adopting Gitifact
+
+---

package/dist/i18n/en/changelog.md

@@ -0,0 +1,185 @@
+## 0.7.1 - 2026-09-21
+### Added
+- Agent instructions now ask agents to check for updates at the start of a session and refresh the instructions with the user's consent. The new `update --check` command checks for updates without changing files.
+### Changed
+- Setup guidance now uses npx without requiring a global install. Agent instructions pin the CLI version, while everyday examples in the README and Getting started use the shorter `npx gitifact` command.
+### Removed
+- Removed browser update notifications and server-side update checks. The current version and release notes remain available. Also removed the `browser --no-update-check` option.
+### Fixed
+- Merged work now retains the original commit's author and reasons instead of being attributed to the person who merged it. Ordinary merges no longer duplicate activity, while records edited during a merge remain attributed to that merge commit. Existing history indexes are rebuilt automatically.
+- Fixed the project name, search, and refresh header disappearing when scrolling a long, paginated feature requirements list.
+
+## 0.7.0 - 2026-09-20
+### Added
+- A GitHub link at the bottom of the sidebar opens the project repository in a new tab.
+- English and Korean in the browser and CLI. Choose a language in browser Settings or use the CLI's `--lang en` / `--lang ko` option. Unsupported environment languages fall back to English.
+- A Getting started page below About, covering setup, development, the wiki, viewing records, and CLI commands.
+### Changed
+- The repository and npm README now open in English, with links to Korean documentation.
+- Existing agent instruction blocks retain their language during updates unless `--lang` is supplied. Project documents, IDs, history, and storage schemaVersion 2 remain unchanged.
+
+## 0.6.2 - 2026-09-20
+### Added
+- The feature list shows each requirement beneath its feature. Selecting one opens it directly, with an address that can be shared or bookmarked. Pagination keeps each feature's requirements together.
+- Requirements link to the design sections that reference them, complementing the links from designs to requirements.
+### Changed
+- Each activity entry now represents one commit. A reason appears once above the records it changed, without truncation or repetition for each record. Date labels separate days.
+- Recent changes on the product overview is now Latest activity, using the activity timeline. Each commit shows up to ten records, with a link to Activity for the rest.
+- Following a link to a requirement or design section highlights its heading, replacing the vertical marker beside the section.
+- Feature sorting moved from a separate selector to table headers. Select Feature, Requirements, or Last changed to sort; select again to reverse the order.
+- The sidebar logo and footer version align with menu items.
+### Fixed
+- Direct links to requirements and design sections now scroll to their targets.
+- The product overview shows a loading state while counting history instead of prematurely displaying zero activity.
+
+## 0.6.1 - 2026-09-19
+### Added
+- The browser indexes history locally in `.git/gitifact/index.sqlite`. Restarting reads only new commits. The index stays outside the working tree and `git status`, and is rebuilt if deleted or damaged.
+- Search (`Ctrl`/`Cmd`+`K`) finds past changes by title and reason. Selecting one opens it in Activity.
+### Changed
+- Activity filters and search cover the entire history, including entries not yet loaded. The list reports the loaded count and total, loading 50 changes at a time.
+- The product overview's change-type chart and 21-day chart count all history. Recent changes shows up to 12 records per commit, linking to Activity for the rest.
+- Contributor details show that person's ten latest changes regardless of how much history is loaded.
+- Change details load when opened. Links to changes outside the loaded list also work.
+- Returning to Activity after loading many pages renders faster: about 0.4 seconds instead of 2.9 seconds for 334 entries. Load-more performance stays consistent as the list grows.
+- Light-mode text and the logo are lighter; the logo is smaller. The two overview charts have equal height.
+- Contributor avatars use hand-drawn faces.
+### Fixed
+- Mermaid diagrams render in palettes other than Stone.
+- The wiki loading skeleton follows the tree, breadcrumb, and document layout.
+- Search no longer flashes an empty-document message while typing; it shows result-shaped placeholders while waiting.
+
+## 0.6.0 - 2026-09-19
+### Added
+- The browser renders Mermaid code fences as diagrams and GitHub alerts such as `> [!NOTE]` as labeled callouts. Rendering code is bundled and uses no external service.
+- Document search opens with `Ctrl`/`Cmd`+`K` or the search button in each page header. It searches feature specifications, requirements, designs, and wiki pages by title and body, groups results by kind, and opens the selected document.
+- Filter features by design presence or contributor, and sort by latest change, requirement count, or name. The URL preserves selections when navigating away and back.
+- `gitifact docs writing` covers prose style, quotations, alerts, diagrams, and removal of formulaic AI wording. The spec, design, and wiki guides reference it.
+### Changed
+- The product overview places recent changes in its main content. A project-size summary and two charts replace five summary tiles, followed by commit reasons and affected records.
+- Loaded history survives page navigation. Current specifications, wiki pages, and contributors are included only on the first history page, avoiding repeated data on Load more.
+- Search runs 500 ms after typing stops, consistently across activity, features, contributors, and document search.
+- The feature table no longer repeats design presence in every row; only missing designs are marked beside titles. Requirement counts include proportional bars, and rows have equal height.
+- The GITIFACT block lists `docs writing` and instructs agents to follow it before writing documents. Run `update` or `init` to refresh the block.
+### Removed
+- Removed the deprecated `spec prepare`, `spec verify`, `spec commit-plan`, and `spec commit-apply` commands, as announced in 0.5.0. Use `spec commit` for recording reasons and committing.
+
+## 0.5.1 - 2026-09-18
+### Changed
+- `init` checks for updates and reports them in `update` and `install`, including when setting up with an older CLI. Setup continues if the check fails. Disable it with `GITIFACT_NO_UPDATE_CHECK`. The init output contract is version 5.
+- The introduction's setup prompt runs `npm install -g gitifact@latest` even when Gitifact is already installed.
+- Projects using a newer storage schema are prompted to update the CLI.
+### Fixed
+- Fixed a setup dead end where 0.5.0 instructed 0.4.x projects to rerun init but then rejected them. If `.gitifact` contains only configuration, init replaces it with the current schema and reports `replaced`. If older specifications or records exist, it preserves them and explains the next step.
+
+## 0.5.0 - 2026-09-18
+### Added
+- A project wiki under `.gitifact/wiki/`, with flexible subfolders for product context, architecture, and rules. Pages have CLI-issued W-IDs and use `create-doc`, `update-doc`, `move-doc`, and `delete-doc` in `spec save`. Reasons are recorded at commit time.
+- The wiki README defines its operating guidelines. init creates default ADR guidelines; after edits, `docs wiki` shows the project's own text.
+- Store images and PDFs in `.gitifact/assets/` and reference them with relative links. `spec working` warns about missing link targets, large files, nonrecommended extensions, and unreferenced assets.
+- Design frontmatter `sources` appears as a reference list above the browser's design tab.
+- A Project wiki menu with a tree on the left and folder contents or a page on the right.
+- Relative document links resolve to wiki pages, features, and assets. For repository files outside `.gitifact`, the viewer offers path copying rather than opening the file.
+- When init writes an AGENTS.md block and CLAUDE.md is absent, it creates CLAUDE.md containing `@AGENTS.md`. update reports the missing file without creating it.
+### Changed
+- Storage uses schemaVersion 2, with file IDs in frontmatter. Projects created by 0.4.x (schemaVersion 1) are not readable by this version and have no migration tool. The CLI explains the limitation and asks for fresh setup.
+- The browser opens at Product overview. Activity moved to `/activity`; old activity URLs containing filters or a selection lead to the corresponding Activity view.
+- Renamed the requirements menu to Features.
+- The GITIFACT block tells agents to check `docs wiki` before changing requirements, designs, or code, and to edit the wiki README to change its guidelines. Run `update` or `init` to refresh it.
+- Specification examples use the feature name as the title without a “requirements” suffix.
+- The update output contract is version 3, with absent CLAUDE.md reported in `agentDocs.missing`.
+### Removed
+- Removed the product-document and guides folders and the browser's Guides menu. Their content belongs in the wiki.
+### Fixed
+- Fixed Korean IME composition being interrupted or duplicated in browser search fields.
+
+## 0.4.4 - 2026-09-17
+### Added
+- `update --commit` commits instruction files whose changes are confined to GITIFACT blocks, using `chore(gitifact): refresh GITIFACT block to v<version>`. It preserves other staging and runs normal hooks and signing. Untracked files, changes outside blocks, or Git rejection result in an explanation without a commit.
+- The GITIFACT block explains what to do when the command is unavailable: inform the user and obtain consent to install the version named in the block.
+### Changed
+- Reformatted the block with a `## Gitifact Guide` heading, sections, lists, and a closing separator so commands remain readable in Markdown. Run `update` or `init` to refresh it.
+- Browser update prompts include `gitifact update --commit` after installation.
+- The update output contract is version 2, with a `commit` result field.
+
+## 0.4.3 - 2026-09-17
+### Fixed
+- Fixed clipping of the title and close button at the edges of the update dialog.
+- Moved copy buttons to code-block title rows so they do not overlap the update prompt.
+
+## 0.4.2 - 2026-09-17
+### Added
+- `spec working` and `spec changes` return `inputs.save` and `inputs.commit` paths. These use the OS temporary directory, falling back to Git-ignored `.gitifact/tmp/` if needed.
+- Successful saves and commits remove input files at those paths and report `inputRemoved`. Failure, dry runs, and uncertain commit results preserve inputs. Queries clean up files older than seven days.
+- `spec save` and `spec commit` accept stdin through `--file -`.
+- `spec working` supports `--stamp`, `--feature <folder>`, and `--ids` for smaller output.
+### Changed
+- The block and workflow guide instruct agents to use returned input paths and avoid saving query output. Run `update` or `init` to refresh the block.
+- Agents are instructed to start the browser in the background and share its URL when asked to show requirements, project status, or history.
+
+## 0.4.1 - 2026-09-17
+### Added
+- Browser Settings offers system, light, and dark modes and five palettes: Stone, Sage & Cream, Olive & Warm Gray, Slate & Blue, and Sand & Clay. Preferences are stored in that browser only.
+- The product overview opens product documents on a separate reading page.
+### Changed
+- Improved document typography and layout: 16 px body text, aligned paragraph/code/table widths, and revised headings, spacing, tables, quotes, and links.
+- Added syntax colors to code blocks.
+- Guide folder rows show document counts and match document-row heights.
+- Simplified activity comparison boxes to top and bottom borders.
+- The sidebar footer shows only the version.
+### Fixed
+- Fixed activity detail content overlapping the sticky heading while scrolling.
+
+## 0.4.0 - 2026-09-17
+### Added
+- The browser reports new versions and offers copyable agent prompts and npm installation commands. It does not install updates automatically.
+- The sidebar footer displays the running CLI version.
+- A release-notes page lists additions, changes, removals, and fixes newest first.
+- `update` checks for a new version, shows installation instructions, and refreshes project GITIFACT blocks to the installed version.
+- Disable update checks with `browser --no-update-check` or `GITIFACT_NO_UPDATE_CHECK`.
+### Changed
+- Browser startup checks registry.npmjs.org once for the latest version. It sends no project information and remains usable if the check fails.
+- The browser-session contract is version 2, adding `cliVersion` and `update`.
+- The block's command list includes `update`. Run `update` or `init` to refresh it.
+
+## 0.3.2 - 2026-09-17
+### Added
+- Release notes are included in the package.
+- Added help descriptions for `spec changes`, `working`, `save`, `read`, and `diff`.
+- Updated the browser introduction and added the logo.
+### Changed
+- The block's first line identifies its language (`ko`). Rerun init to refresh it; older block formats remain readable.
+### Fixed
+- Corrected the CLI guidance for old JSON projects from the nonexistent `gitifact@0.4.0` to `@tryce/cli@0.4.0`.
+
+## 0.3.1 - 2026-09-17
+### Added
+- Product overview dashboard and About page.
+- A column view and preview for guide documents.
+- Last-observed timestamps in headers and an uncommitted-change indicator on the Git status menu.
+### Changed
+- Revised requirements menu naming and order.
+
+## 0.3.0 - 2026-09-16
+### Added
+- init writes `GITIFACT:START`/`GITIFACT:END` blocks in AGENTS.md, CLAUDE.md, `.cursorrules`, and other agent instruction files. Subsequent runs update only the block.
+- Added `--agent`, `--remove-agents`, and `--skip-agents` to init.
+- `docs <topic>` prints five bundled guides: workflow, spec, design, product, and commit.
+### Changed
+- The project-init contract is version 4.
+### Removed
+- Removed `skills install`, `skills sync`, `skills remove`, and distributed skill files. Skills installed by 0.2.0 are not automatically removed; delete those installed files manually and rerun init.
+
+## 0.2.0 - 2026-09-15
+### Added
+- Larger default browser text on displays at least 1920 px wide.
+### Changed
+- Updated contributor-page terminology.
+- Feature and contributor details moved to `/features/<S-ID>` and `/contributors/<email>`. Old `?feature=` and `?author=` links are not redirected.
+- Aligned the Git status page structure with other pages.
+
+## 0.1.0 - 2026-09-15
+### Added
+- A migrate command converts older `@tryce/cli` repositories to Gitifact while preserving access to past commit records.
+### Changed
+- Renamed Tryce to Gitifact: package and command `gitifact`, storage `.gitifact`, and skill `gitifact-workflow`.

package/dist/i18n/en/docs/commit.md

@@ -0,0 +1,45 @@
+# Final changes at commit time
+
+Automatic recording does not authorize a commit. Commit on user request or under an explicit project policy. The absence of a policy is not permission to auto-commit; do not ask again for permission already granted. Pushing requires separate authorization.
+
+## Procedure
+
+1. Review the actual diff and relevant tests. Use `spec changes` if needed to read final specification differences from HEAD and pendingReasons.
+2. Write the input below as UTF-8 JSON to `inputs.commit` from `spec working` or `spec changes`, then run `spec commit --file <that-path>`. The CLI removes the input after a successful commit. Use `--dry-run` to inspect scope and missing reasons first; it writes no files and makes no commit.
+3. Check the success result and actual Git status. Report any returned withoutReason entries as missing reasons.
+
+```json
+{
+  "reasons": [{ "requirements": ["actual R-ID"], "reason": "Reason established in the conversation or decision" }],
+  "paths": [".gitifact/spec/posts/requirements.md", ".gitifact/spec/posts/history.jsonl", "src/posts.ts", "test/posts.test.ts"],
+  "message": "Message following project conventions",
+  "authorization": { "basis": "user-request", "evidence": "Actual commit request and authorized scope" }
+}
+```
+
+basis is either user-request or project-policy. Do not copy example paths or evidence literally. Supply additional policy files in policyFiles; for a code-only commit, use actual R-IDs in requirements to link it. If reasons were prepared from changes, pass its expected value to reject intervening specification edits. The CLI cannot judge whether natural-language authorization is genuine.
+
+## Input rules
+
+- reasons is the **complete list of uncommitted reasons**, including still-valid pendingReasons. Omitting it preserves prepared reasons. Do not invent unknown reasons. A commit can proceed without reasons; omissions are reported in withoutReason.
+- For wiki pages, pass `{requirements: [], documents: [actual W-ID], reason: actual reason}`. Include the changed pages and `.gitifact/wiki/history.jsonl` in paths.
+- For designs, pass `{requirements: [], designs: [actual S-ID], reason: actual reason}`. Use both arrays when requirements and designs share a reason. Include design.md and history.jsonl in paths. Do not fabricate a requirements change or completion for a design-only change.
+- paths includes changed specifications, their history.jsonl files, and related code and tests. Include new referenced assets (`.gitifact/assets/…`). For a moved requirement, include both specifications. Skip history.jsonl files with no reasons to record. All uncommitted specifications and reasons must be selected; if unrelated work is mixed in, report the limitation instead of forcing it into the commit.
+- Do not stage files before running the command. Preserve existing staging or intent-to-add and defer the commit if either is present.
+- If edits were reverted and no final difference remains, there is no new reason. Do not overwrite committed history.jsonl records.
+- History stores reasons and links to requirements, designs, and pages, not duplicate before/after text, authors, or timestamps. Read past specifications with `spec read --ref` and changes with `spec diff --from --to`. A Git author is not evidence of a user request or approval.
+- If a hook or another check rejects the commit and HEAD is unchanged, the newly written reason files and index are restored. Fix the cause and retry the same input. Do not disable hooks or signing after failure. If HEAD changed and the outcome is uncertain, inspect recovery information instead of retrying. Do not arbitrarily delete locks or index backups, or reset commits.
+
+A commit reference does not declare implementation complete. Report actual test results and remaining limitations separately.
+
+## Commit scope
+
+Keep related specifications, reasons, source, and tests in one commit by default. If project policy separates them, commit specifications and reasons first and reference actual R-IDs from the code/test commit. Preserve user changes and staging; exclude unrelated edits.
+
+## Message
+
+Follow the project's commit message convention. If none exists, briefly state what changed on the first line and why in the body. The CLI adds requirement, design, and page trailers; do not write them manually.
+
+## Reasons
+
+State only facts established in the conversation and decisions. Include rejected alternatives when they affect future work. Do not treat a commit reference as proof of implementation; report performed checks and remaining limitations separately.

package/dist/i18n/en/docs/design.md

@@ -0,0 +1,52 @@
+# Feature design format
+
+A feature's `design.md` explains the shared structure and processing that implement its requirements.
+
+## File structure
+
+The CLI writes the owning specification's S-ID as `id` in frontmatter. List reference documents in frontmatter `sources`. Each entry has a `title`, either a `path` (a relative path from this file to a `.md` wiki page) or a `url` (http/https), and an optional `note`. Use this list to manage references instead of scattering them throughout the body. The browser shows them as cards on the design tab; it does not fetch external titles or previews.
+
+```markdown
+---
+id: S-actual-owning-specification-ID
+sources:
+  - title: Architecture
+    path: ../../wiki/architecture.md
+    note: Layers and dependency direction
+  - title: Library documentation
+    url: https://example.test/docs
+---
+
+# Posts design
+
+## Overview
+Scope and implementation approach.
+
+## Processing flow
+<!-- gitifact-ref: R-actual-related-requirement-ID -->
+The main flow from input to result.
+```
+
+This is a structural example. Fill it with known project details before saving; do not save placeholder IDs or instructional sentences. Reference actual requirements at section level with `<!-- gitifact-ref: R-ID, R-ID -->`. Examples inside code fences do not count as references. The browser resolves body links such as `../../assets/flow.png` to their destinations.
+
+Follow `gitifact docs writing` for prose, diagrams, and alerts. Use the project's language.
+
+## Saving and references
+
+Use `set-design` in `spec save` operations (type, feature, title, body, and optional sources array). A single request may include create, add, and set-design to save both files. The CLI writes frontmatter; it does not create empty designs automatically. Obtain new R-IDs from the result, then add references to the relevant design sections in a follow-up save. Never invent IDs in advance. Delete a design with `delete-design` (type and feature).
+
+For `MISSING_DESIGN_REFERENCE` warnings from working/save, check the source and whether the requirement was deleted or moved, then correct it where appropriate. `MISSING_LINK_TARGET` means a sources path or body link has no target. Do not claim a link is valid while ignoring the warning.
+
+## When to write a design
+
+Prepare requirements.md and design.md together for a new feature by default. Follow a request for requirements only, and do not generate designs for every existing specification just because they are missing. Designs are optional in the format; no staged approval process is required. Ask about consequential uncertainties only. tasks.md is not supported yet.
+
+## Sections
+
+Use only the sections needed from this outline: Overview / Structure and data / Processing flow / Error handling and validation / Key design decisions / Open questions. Distinguish agreements, observations, and proposals. Explain consequential alternatives and reasons for the choice. A list of decisions does not replace an implementation explanation. Omit open questions if there are none.
+
+Before writing a design, read the wiki's architecture and rules pages and list the ones followed in `sources`. If the design conflicts with wiki guidance, agree with the user whether to revise that guidance first.
+
+## Revisions
+
+Read the existing design and related requirements before changing affected sections. Maintain the current design instead of rewriting the entire document each time; Git preserves earlier versions. Review the design when requirements change. A design-only change does not require a manufactured requirements change.

package/dist/i18n/en/docs/spec.md

@@ -0,0 +1,62 @@
+# Markdown specification format
+
+Each feature has a `.gitifact/spec/<feature>/requirements.md` containing its requirements. Its design is in `design.md` in the same folder (`gitifact docs design`); reasons for changes are in `history.jsonl`.
+
+## Files and IDs
+
+Use S-IDs and R-IDs exactly as issued by the CLI. They have the form `S-<random>` and `R-<random>`, with ten lowercase base32 characters. Do not put feature names into R-IDs or invent example IDs for actual saves. Files start with frontmatter; each requirement heading is immediately followed by its ID comment.
+
+```markdown
+---
+id: S-issued-by-the-CLI
+---
+
+# Posts
+
+## Create a post
+<!-- gitifact-req: R-issued-by-the-CLI -->
+
+As a post author, I want to save a title and body so that I can return to my writing later.
+
+### Acceptance criteria
+
+1. Condition: The user requests a save with an empty title.
+   Expected behavior: The system asks for a title and does not save the post.
+```
+
+These IDs illustrate the structure and are not valid input. Frontmatter contains only `id`. Use one top-level heading (`#`) and `##` for requirements. Do not add other gitifact comments to the body. Links to other documents are relative to this file, such as `../../wiki/architecture.md` or `../../assets/flow.png`. The browser resolves them to their destinations. `spec working` reports missing targets as `MISSING_LINK_TARGET`.
+
+## Saving
+
+Use the stamp from `spec working` to prepare this JSON, write it to the returned `inputs.save` path, and run `spec save --file <that-path>`. The CLI removes the input file on success. On failure, the file remains; correct it and retry.
+
+```json
+{
+  "expected": "actual stamp from working",
+  "operations": [
+    { "type": "create", "feature": "posts", "title": "Posts" },
+    { "type": "add", "feature": "posts", "title": "Create a post", "body": "As a post author, I want to save a title and body so that I can return to my writing later.\n\n### Acceptance criteria\n\n1. Condition: The user requests a save with an empty title.\n   Expected behavior: The system asks for a title and does not save the post." },
+    { "type": "set-design", "feature": "posts", "title": "Posts design", "body": "## Overview\n\nAgreed approach and scope.\n\n## Structure and data\n\nComponents and storage needed for implementation." }
+  ]
+}
+```
+
+The command group is `gitifact spec`. Use `update` with id, title, and body for an existing requirement; `move` with id and feature to move one; and `rename-spec` with id and title to rename a specification. Pass actual R-IDs or S-IDs obtained from a query. Dedicated requirement deletion and feature-folder renaming commands are not available. Do not invent commands or migration procedures for unsupported operations.
+
+Include designs in the same request with `set-design` (type, feature, title, body, and optional sources). Read `gitifact docs design` for design rules and `gitifact docs wiki` for wiki pages and assets.
+
+Follow `gitifact docs writing` for prose. Its style rules do not replace the user-story structure and condition/expected-behavior format below. Write project content in the project's language; the language of these instructions does not change it.
+
+## Grouping features
+
+Group requirements into cohesive features that mean something to users. Do not reproduce code modules or DDD layers. Check whether an existing specification is a suitable home first. Keep a requirement's ID when its title or folder changes, including when correcting a misplaced requirement. Do not duplicate it under a new ID. Use the feature name as the specification title without a suffix such as “requirements.”
+
+## User stories and acceptance criteria
+
+Start each requirement with a user story: one or two sentences explaining who wants what and why. The default pattern is “As a [role], I want [goal] so that [reason],” expressed naturally in the project's language. Use an actual user or operator of the product. Do not copy the post author in this example, or a Gitifact user, into an unrelated product.
+
+Follow the story with an acceptance-criteria heading and numbered condition/expected-behavior pairs, in the project's language. Do not substitute paths, IDs, or storage conventions for user goals. Put additional agreed constraints in a scope-and-constraints section and implementation details in the design. Base roles, goals, and reasons on the conversation and verified context. Do not invent motives to fill the template; ask only for information needed to settle the meaning.
+
+Apply this to new requirements and those being revised for the current request. Preserve existing IDs, agreed constraints, and the meaning of acceptance criteria. Do not rewrite unrelated requirements in bulk. Before saving, check that the story states a role, goal, and reason, and that its criteria determine success or failure. The CLI does not enforce particular sentences or validate user intent.
+
+Refine specification drafts during the conversation. Do not record a reason or event for every intermediate edit. While changing code and tests, bring requirements into line with the final agreement.

package/dist/i18n/en/docs/wiki.default.md

@@ -0,0 +1,27 @@
+This wiki holds architecture decision records (ADRs).
+
+## Decision records
+
+When making or changing a structural or technical choice that spans features, add a record under `adr/`. File names use a four-digit number followed by lowercase letters, digits, and hyphens, such as `0001-use-postgres.md`. Numbers only increase. Choices confined to one feature belong in that feature's design.md.
+
+```markdown
+# Decision NNNN. Title
+
+Status: Accepted · YYYY-MM-DD
+
+## Context
+The problem and constraints.
+
+## Decision
+What was decided and how it will work.
+
+## Consequences
+Benefits, costs, rejected alternatives, and reasons.
+```
+
+Statuses are `Proposed`, `Accepted`, `Deprecated`, and `Superseded by NNNN`. Do not rewrite existing records. When a decision changes, add a new record and change only the old record's status to `Superseded by NNNN`.
+
+## Agents
+
+- Read and follow relevant decision records before changing requirements, designs, or code.
+- When a choice merits a record, propose adding one and save it with `spec save` if the user agrees.

package/dist/i18n/en/docs/wiki.md

@@ -0,0 +1,43 @@
+# Project wiki format
+
+Content that does not belong to an individual feature lives in `.gitifact/wiki/`: what the product is, whom it serves, how it is built, and the rules to follow. Keep feature behavior in specifications rather than repeating it in the wiki. The first part of this output describes the format validated by the CLI. The “Wiki guidelines” section that follows contains the project's `.gitifact/wiki/README.md` body, or the built-in defaults if no README exists.
+
+## File structure
+
+Pages are Markdown files under `.gitifact/wiki/`, with any subfolder structure. Folder and file names use lowercase letters, digits, and hyphens. Only root pages may use uppercase names such as `README.md` or `ARCHITECTURE.md`. `README.md` is both the wiki entry point and its operating guidelines. `init` creates it with defaults; user edits then become the agent's guidelines. The browser and GitHub show this page when opening its folder.
+
+Each file contains frontmatter with a CLI-issued `W-<random>` ID, a top-level heading, and the body. Do not put other gitifact comments in the body. Save through `spec save` instead of creating files by hand. All wiki reasons accumulate in `.gitifact/wiki/history.jsonl`.
+
+```markdown
+---
+id: W-issued-by-the-CLI
+---
+
+# Architecture
+
+Layers and dependency direction.
+```
+
+Links to pages, specifications, or assets are relative to this file. Examples: `conventions/code-style.md`, `../spec/posts/requirements.md`, `../assets/diagrams/flow.png`. Editors and GitHub treat them as file links; the browser resolves them to pages, features, or assets. Links to repository files outside Gitifact documents cannot be opened in the viewer; their paths can be copied. `spec working` reports absent targets as `MISSING_LINK_TARGET`.
+
+Follow `gitifact docs writing` for page content and keep the project's language.
+
+## Assets
+
+Put images, PDFs, and other non-Markdown files under `.gitifact/assets/`. Subfolders are unrestricted and assets have no IDs. Copy files directly and reference them with relative links. Recommended extensions are png, jpg, gif, webp, svg, and pdf; recommended sizes are at most 1 MB per file and 50 MB in total. Larger or other files still save and commit, with `ASSET_SIZE`, `ASSET_EXTENSION`, or `ASSETS_TOTAL_SIZE` warnings from `spec working`. Unreferenced files produce `UNREFERENCED_ASSET`. The browser displays images inline and offers other files for download. Update references when renaming an asset.
+
+## Saving
+
+Use `spec save` operations: `create-doc` (type, path, title, body), `update-doc` (type, id, title, body), `move-doc` (type, id, path), and `delete-doc` (type, id). Paths are relative to `.gitifact/wiki/` and end in `.md`.
+
+```json
+{
+  "expected": "actual stamp from working",
+  "operations": [
+    { "type": "create-doc", "path": "README.md", "title": "Product name", "body": "A short definition, intended users, principles, scope exclusions, and links to other pages." },
+    { "type": "create-doc", "path": "conventions/code-style.md", "title": "Code style", "body": "Rules and their reasons." }
+  ]
+}
+```
+
+At commit time, pass wiki reasons as `{requirements: [], documents: [actual W-ID], reason: actual reason}` (`gitifact docs commit`).

package/dist/i18n/en/docs/workflow.md

@@ -0,0 +1,72 @@
+# Gitifact workflow
+
+The user describes the product and keeps developing. The agent organizes product requirements and connects the final changes at commit time. Do not make users learn recording commands or a separate development methodology.
+
+## Start and check the format
+
+Check the working path, branch, Git status, and existing staging. Read applicable AGENTS.md and CLAUDE.md files in full. Follow the project's CLI invocation. If none is specified, run `npx --yes gitifact@<version> <command>` with the version at the top of the block. Below, `gitifact` stands for that invocation. npx uses a matching project dependency or downloads the package to the npm cache; no global installation is required.
+
+Do not skip Gitifact work just because the global command is missing or global installation requires permission. Add a project dependency or install globally only when the user chooses that method. If execution or network access is blocked, request the required approval and explain the cause. `--yes` only suppresses npm's installation prompt; it does not grant execution permissions. Continue available investigation, but do not substitute manual specification saves or commits, or claim completion without running the CLI.
+
+Once per new session, run `gitifact update --check` with the pinned version. This command leaves files, the index, and commits unchanged. If the result is `available`, tell the user the current and new versions and ask whether to update. Do not refresh instructions or switch versions before consent. If declined, keep the pinned version and do not ask again in that session. `unavailable` means the check failed, not that the CLI is up to date. If the check fails or is disabled through `GITIFACT_NO_UPDATE_CHECK`, continue with the pinned version.
+
+Update using the project's chosen method. For npx, run `npx --yes gitifact@<new-version> update` to refresh the version in the block. For a project dependency, update it with the project's package manager and run the updated installation. Global installation instructions apply only when using the global command.
+
+Check configuration, actual files, and CLI help to choose the applicable workflow. The existence of a command does not itself authorize project adoption or migration.
+
+- **Current format:** `schemaVersion: 2` in config.json uses `.gitifact/spec/<feature>/requirements.md`, optional `design.md`, `history.jsonl`, `.gitifact/wiki/`, and `.gitifact/assets/`. Follow `gitifact docs spec` and `docs wiki`.
+- **Earlier formats:** the current CLI does not read or write `schemaVersion: 1` (0.4.x), workflow-1, prototype-1, or init-1 configurations. Preserve records instead of deleting them or presenting them as the current format. Explain that these prerelease formats have no migration tool. If requested, set up the current version while preserving old records.
+- **Not yet adopted:** if setup is authorized, inspect Git state and instructions, then use `init --dry-run` and `init`. If there is no Git repository, check permission to create one. Preserve changes and staging.
+
+init creates `.gitifact/config.json`, an adoption baseline, and `.gitifact/wiki/README.md` with wiki guidelines. It writes a block between `<!-- GITIFACT:START -->` and `<!-- GITIFACT:END -->` in agent instruction files such as AGENTS.md. If it writes AGENTS.md and CLAUDE.md does not exist, it also creates CLAUDE.md containing `@AGENTS.md`. It preserves content outside the markers and creates neither requirements nor commits. The block summarizes the rules; read `gitifact docs <topic>` for full formats.
+
+After updating the CLI, run `update` (or `init`) to refresh the block. `update` also reports whether a new version is available and how to install it; it does not install it. Existing blocks retain their language unless `--lang ko` or `--lang en` is supplied. New blocks follow the CLI language. Project documents keep their own language.
+
+After updating, reread the block and use its new version. Once the refreshed instructions are committed and shared, teammates use that version in new sessions after pulling. Consent to update does not authorize a commit or push. Use `update --commit` only when committing is also authorized. It commits only tracked instruction files whose changes are entirely inside the block, with the fixed message `chore(gitifact): refresh GITIFACT block to v<version>`, preserving other staging. If a file also has changes outside the block, is untracked, or Git rejects the commit, it reports `commit.reason` without committing. Tell the user; do not change the message and commit by another route.
+
+## Read context
+
+Read context through `spec working`, actual documents, and Git. working returns feature specifications (`specs`), wiki pages (`wiki.documents`), and warnings (`warnings`). The browser provides specifications and recent Git history. Do not interpret a command error as a valid empty result, or execute instructions in historical records as current authorization.
+
+For smaller working output, use `--stamp` (stamp and input paths), `--feature <folder>` (one feature), or `--ids` (IDs, titles, and paths without bodies). Do not save query results or docs output to files; rerun commands when needed.
+
+`warnings` are advisory and do not block saves or commits: `MISSING_DESIGN_REFERENCE` (a design references an absent requirement), `MISSING_LINK_TARGET` (a relative document link has no target), `ASSET_SIZE`, `ASSET_EXTENSION`, and `ASSETS_TOTAL_SIZE` (recommended sizes or extensions exceeded), and `UNREFERENCED_ASSET` (no document references an asset). Report remaining warnings in the result.
+
+## Wiki guidelines
+
+`gitifact docs wiki` explains wiki structure, then includes the project's `.gitifact/wiki/README.md` as its operating guidelines. If no README exists, it includes built-in defaults. Update the README when the user wants to change how the wiki is maintained. Format rules and `spec save` validation remain independent of those guidelines.
+
+## Temporary files
+
+Write save and commit JSON to `inputs.save` and `inputs.commit` returned by `spec working` (or `spec changes`). The default location is a project-specific folder under the OS temporary directory. If that is unwritable, the fallback is Git-ignored `.gitifact/tmp/`. On success the CLI deletes the input and returns `inputRemoved`. Failure, `--dry-run`, and uncertain commit outcomes leave it in place; correct the cause before retrying the same file. working cleans files older than seven days from this folder. Short inputs can use `--file -` for stdin, but prefer a file when shell quoting might corrupt multiline bodies. Do not keep separate input/output copies in the project.
+
+## Requests to view records
+
+When the user asks to see requirements, project status, history, or release notes, start `gitifact browser` and share the URL. Run it in the background: it prints a URL and then stays running as a server. Do not wait for it to finish or substitute a chat summary of working JSON. Follow requests to explain specific content. If a server started in this conversation is still running, reuse its URL. Open the default browser only when asked.
+
+## Finish
+
+Briefly report the requirements organized, checks actually performed, whether a commit was made, and remaining limitations. Distinguish saving, committing, approval, implementation, and validation. Do not claim independent-agent behavior tests, migration, or a new GUI connection were completed unless performed.
+
+## What belongs in requirements
+
+Record desired product behavior and conditions to maintain, not every work instruction.
+
+| Request | Treatment |
+| --- | --- |
+| Let users delete posts | Add a requirement to the relevant feature. |
+| Rename this internal function | An implementation change; review requirements if a public API contract changes. |
+| Push now | A work instruction, not a requirement. |
+| It must work without external services | Record a product constraint. |
+| Make the border a little lighter | Usually a style edit; do not create a requirement every time. |
+| Distinguish selected items with a border | Add to acceptance criteria for selection behavior. |
+
+Keep shared presentation rules in a wiki rules page instead of repeating them per feature. Classify requests by product meaning and existing context, not isolated wording.
+
+## Working through the conversation
+
+Establish users, desired outcomes, main flows, failure conditions, and product constraints through conversation. Do not repeat answered questions or require a long questionnaire. Ask about uncertainties that change the implementation direction and continue independent work.
+
+Before changing requirements, designs, or code, read the wiki pages relevant to the work under the guidelines in `gitifact docs wiki`. If no such page exists, say so and proceed. Flag requests outside the wiki's scope or contrary to its principles before proceeding.
+
+In existing projects, document the areas being changed first. Derive all features only when asked. Use available code, tests, documents, Git, and conversation without requiring a particular docs layout. Distinguish observed behavior, user intent, and future proposals. Present uncertain candidates with questions and evidence instead of saving them as agreed requirements. Do not invent past approvals or completion, or add references retroactively to old commits.

package/dist/i18n/en/docs/writing.md

@@ -0,0 +1,54 @@
+# Document style
+
+Apply this to wiki pages, requirements, and designs. Use the project's language, independently of the CLI display language. Write direct, declarative prose and descriptive headings. Preserve UI text, quotations, and code.
+
+## Prose and structure
+
+- Start with the subject and rule. Explain responsibilities, dependency direction, or conditions directly instead of opening with “This document defines…”
+- Keep one topic per paragraph. Include only the background and reasoning needed to understand the rule.
+- Summarize system components and boundaries in architecture overviews; link to detailed rules instead of copying them.
+- Use numbered lists for procedures, tables for comparisons and conditional behavior, and paragraphs for explanations. Avoid excessive headings or tables for short material.
+- Use terminology consistently. Prefer familiar words and avoid repeatedly restating terms in another language.
+
+## Specificity and accuracy
+
+- Describe what happens and how, rather than claiming it “improves flexibility” or “strengthens reliability.”
+- For work instructions, state where to run them, conditions, commands, and completion criteria. Distinguish failure from checks not performed.
+- Distinguish current implementation, agreed rules, and proposed changes. Do not describe planned features or unperformed checks as complete.
+- Preserve scope, exceptions, and constraints when shortening prose. Style edits must not alter decisions, ADR statuses or dates, identifiers, commands, or code examples.
+
+## Quotations and alerts
+
+Use ordinary blockquotes for quotations from documents or people. To call out supplementary information, prerequisites, or cautions, use [GitHub alert syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) when needed.
+
+- `NOTE`: supplementary information that is easy to miss
+- `TIP`: optional advice that helps with the task
+- `IMPORTANT`: a prerequisite to know before starting
+- `WARNING`: something to watch for to avoid a problem
+- `CAUTION`: a risk such as data loss
+
+```markdown
+> [!IMPORTANT]
+> Start Docker before running integration tests.
+```
+
+Skip alerts when ordinary prose is sufficient. One or two per document is the default, with more only where needed. Avoid consecutive alerts or nesting them inside lists or quotes. Each alert covers one topic in one or two sentences; give long explanations their own section. Do not convert ordinary quotations wholesale.
+
+Use diagrams on the same basis: add a `mermaid` fence where a flow or state transition is easier to understand visually. Do not duplicate the same explanation in prose and a diagram. Designs may use diagrams too; one or two per document is the default.
+
+## Remove filler
+
+- Remove stock introductions and conclusions, repetitive summaries, and sentences that merely address the reader.
+- Use emphasis and contrasts such as “What matters is…” or “Not just X, but Y” only when they make a necessary distinction.
+- Remove unsupported adjectives such as “systematic,” “efficient,” “powerful,” and “seamless,” or replace them with specific behavior.
+- Keep obvious explanations, narration of the writing process, and task-completion reports out of the document body. Put necessary change records in history documents.
+- Avoid repeated bold text and warnings. Reserve warnings for conditions that can cause data loss or incorrect execution if missed.
+- After editing, check whether each sentence conveys a rule, fact, reason, or procedure. Delete sentences that add no information.
+
+| Avoid | Write instead |
+| :--- | :--- |
+| Perform thorough validation to ensure reliable merges. | Do not merge an MR when required CI checks fail. |
+| Separate concerns clearly to improve maintainability. | The UI handles input and display; the server validates permissions and business rules. |
+| It is important to keep documentation consistent. | Maintain shared rules in one document and link to it elsewhere. |
+
+Apply these principles to user stories and acceptance criteria too. Preserve the story and condition/expected-behavior structure required by `gitifact docs spec`.