Imported from NomaDamas/jikji (AGENTS.md). Install upstream with npx skills add NomaDamas/jikji. Copyright stays with the author.

Jikji project guide

Jikji is a separate project from Folder1004.

Product identity

• Jikji prepares local folders for AI-agent discovery without moving, renaming, or deleting user files.
• It creates text-first knowledge maps and parser caches under .jikji/ plus a root .jikji_agent_map.md (legacy 000_JIKJI_AGENT_MAP.md).
• It is meant to be used by local agents such as Hermes/Codex through CLI commands or skills.
• Folder1004 remains the GUI product for physically organizing messy Desktop/Downloads-style folders.

Safety boundary

• Default and expected behavior is non-destructive.
• Never reorganize user folders in this repo unless a future feature explicitly adds a separate, warned physical mode.
• .jikji/ and .jikji_agent_map.md are generated artifacts and may be regenerated.

Generated artifact ownership

Jikji may regenerate only its documented artifacts: .jikji/manifest.json, .jikji/*.jsonl, .jikji/search_index.sqlite, .jikji/agent_map.md, .jikji/agent_routes.md, .jikji/agent_skill_context.md, .jikji/human_guide.md, .jikji/autorag_manifest.json, .jikji/corpus_profile.json, .jikji/intent_taxonomy.json, .jikji/knowledge_graph.json, .jikji/llm_wiki_schema.md, .jikji/wiki/, .jikji/wiki/sources/, .jikji/doc_text/, .jikji/doc_meta/, .jikji/eval/, .jikji/.lock, root .jikji_agent_map.md (legacy 000_JIKJI_AGENT_MAP.md), and Jikji routing blocks inside AGENTS.md, CLAUDE.md, and .cursorrules. Retired generated artifacts listed in manifest.json under retired_cleanup_paths may be removed during prepare. Do not delete arbitrary user-created files under .jikji/.

Local-agent standard docs live in docs/local-agent-search-standard.md, docs/schema.md, and docs/agent-usage.md.

Repository layout

• crates/ contains the Rust workspace and shipped CLI.
• python/jikji/ contains the Python package for reference behavior, benchmarks, golden capture, and optional media support.
• tests/parity/, tests/golden/, and tools/parity/ are cross-stack parity assets shared by Rust and Python.
• Root pyproject.toml is workspace/tooling configuration; Python package metadata lives in python/jikji/pyproject.toml.

Current commands

jikji prepare /path/to/folder   # create/update .jikji and root map
jikji prepare /path/to/folder --no-agent-rules  # skip routing block updates
jikji refresh /path/to/folder   # alias for prepare
jikji map /path/to/folder       # print generated map
jikji doctor /path/to/folder    # verify expected artifacts
jikji find /path/to/folder "query" --json
jikji agent-skill-install --agent all --json

Local dev:

python3 -m venv .venv
.venv/bin/pip install -e python/jikji
.venv/bin/pip install pytest ruff
.venv/bin/ruff check python/jikji/src python/jikji/tests tests/parity tools/parity
.venv/bin/pytest python/jikji/tests tests/parity -q
.venv/bin/python -m compileall -q python/jikji/src python/jikji/tests tests/parity tools/parity

Resume context

The first implementation was split out of Folder1004 on 2026-05-23. It currently includes scanner, metadata collection, parser registry, document text caching, JSONL indexes, and Markdown map generation. Next useful work: stabilize packaging, improve incremental refresh, add watcher/daemon optionally, formalize Hermes/Codex skill docs, and add larger corpus benchmarks.

ABSOLUTE RULE — JIKJI FIRST: for every bounded local file, folder, metadata, or document-content discovery request, the first discovery tool call MUST be jikji find ROOT "query" --json, even when the user did not mention Jikji. Do not begin with grep, rg, glob, find, fd, ls, tree, cat, skills_list, or raw filesystem crawling. Obey the machine-readable index_status, handoff_action, answerability, retry_proof, raw_fallback_allowed, max_jikji_retries, max_raw_fallback_commands, and tool_call_policy fields. On direct_use/answerable_from_payload, return Jikji paths in order and perform no raw discovery. On missing, stale, failure, empty, or clearly wrong results, run exactly one Jikji retry; raw fallback is allowed only when that retry yields raw_fallback_after_retry. Never move, rename, delete, or reorganize user files.