---
name: linta
description: Maintain Linta Markdown knowledge bases from Codex. Use when the user mentions Linta, asks to create or inspect a Linta knowledge base, ingest raw sources, update wiki pages, build indexes, export current context, configure agent access, or work in a repository generated by Linta.
---

# Linta

Linta is a framework for building LLM-compiled Markdown knowledge bases. Use it to keep raw sources immutable, compile source-backed wiki context, and expose reviewed knowledge to agents.

## Working Rules

- Read the nearest `AGENTS.md` before editing.
- If the target is a generated knowledge base, also read `ai_kb/schema/AGENTS.md`.
- Do not mutate files under `ai_kb/raw/` or `raw/`.
- Keep generated templates deterministic.
- Keep semantic claims source-backed through source cards, source manifests, wiki links, or explicit citations.
- Do not commit private IP addresses, real domains, credentials, bearer tokens, OAuth client secrets, approval tokens, or personal knowledge-base paths.
- Use placeholders such as `https://your-linta.example.com`, `replace-with-client-secret`, and `./MyKnowledgeBase` in committed docs.
- Do not call external LLM APIs in tests.
- If a new Linta CLI command is added, add tests for it.
- Keep `README.md` and `README_CN.md` aligned when changing user-facing docs.

## Locate the Target

1. If the user gives a path, use that path.
2. If the current directory contains `pyproject.toml` with `project.name = "linta"`, treat it as the Linta source repository.
3. If the current directory contains `ai_kb/schema/AGENTS.md`, treat it as a Linta knowledge-base root.
4. If unsure, inspect with `pwd`, `rg --files`, and `linta doctor <path>` before editing.

## Prefer These Commands

From an installed environment:

```bash
linta --version
linta doctor ./MyKnowledgeBase
linta manifest scan ./MyKnowledgeBase
linta source-card create ./MyKnowledgeBase ai_kb/raw/meetings/example.md
linta prompt ingest ./MyKnowledgeBase ai_kb/raw/meetings/example.md
linta prompt entities ./MyKnowledgeBase ai_kb/raw/meetings/example.md
linta index build ./MyKnowledgeBase
linta lint ./MyKnowledgeBase
linta export current ./MyKnowledgeBase
```

From the Linta source repository, prefer the local checkout when package installation is not confirmed:

```bash
PYTHONPATH=src .venv/bin/python -m linta --version
PYTHONPATH=src .venv/bin/python -m linta doctor ./MyKnowledgeBase
pytest
ruff check .
```

If `.venv/bin/python` does not have the runtime dependencies, check for another project virtual
environment such as `.venv311/bin/python` before falling back to the system `python3`.

## Ingest Workflow

Use this shape when the user asks Codex to organize new material:

1. Confirm the knowledge-base root and source path.
2. If the source is outside the knowledge base, use `linta raw import`.
3. Create or refresh the source card with `linta source-card create`.
4. Render the relevant prompt with `linta prompt ingest`, `linta prompt entities`, or `linta prompt lint-ai`.
5. Update wiki drafts, source cards, entity pages, portfolio pages, or indexes as the prompt requires.
6. Run `linta index build` and `linta lint`.
7. Show changed files and any human review questions.

## Safety Boundaries

- Do not silently promote `ai_kb/wiki/current_draft/` to `ai_kb/wiki/current/`.
- Do not edit `ai_kb/raw/`; use imports or source cards instead.
- Do not hard-code business-specific examples into core modules or templates.
- Keep Hermes, Claude Desktop, Codex, and remote MCP integration values optional and placeholder-driven.