# ionet-ai

This repository is a local knowledge base for `ionet`. It preserves explainable,
maintainable, and governable knowledge assets and assembly rules.

Its current role is a **local-first full-repository knowledge base**: users work
from a complete local checkout.

## Core Idea

The knowledge base uses a three-layer structure:

- `Knowledge Assets`
  Stable and candidate knowledge assets.
- `Skill Pack`
  Task-oriented skill definitions, rule assembly, and output modes.
- `MCP / CLI`
  Request diagnosis, context assembly, evidence search, and generation boundary
  control over the full repository source tree.

The design focus is not a larger RAG system. It is a constrained, explainable,
and maintainable ionet-oriented knowledge system.

## Public Discovery

Public source and discovery entry points:

- GitHub source: <https://github.com/iohao/ionet-ai>
- Public Pages entry: <https://iohao.github.io/ionet-ai/>
- Small machine entry: <https://iohao.github.io/ionet-ai/llms.txt>
- Full machine entry: <https://iohao.github.io/ionet-ai/llms-full.txt>
- Structured map: <https://iohao.github.io/ionet-ai/ai-index.yaml>
- Structured rules: <https://iohao.github.io/ionet-ai/ai-rules.yaml>
- Sitemap: <https://iohao.github.io/ionet-ai/sitemap.xml>

See [AI discovery and public indexing](docs/ai-discovery.md) for crawler policy
and search-engine submission notes.

## Local Installation

Run this from the repository root:

```bash
bash scripts/install-project.sh --project /path/to/your-project
```

This command:

- Copies visible knowledge sources for Codex CLI into the target project's
  `.codex/skills/ionet-ai/`
- Writes the target project's `.mcp.json` for Claude Code CLI and other
  project-level MCP clients
- Generates the target project's local Codex CLI launcher `codex-ionet.sh`
- Writes or updates the Codex project instruction managed block in the target
  project's `AGENTS.md`
- Writes or updates the Claude Code project instruction managed block in the
  target project's `CLAUDE.md`

By default, MCP runs through the full repository:

```bash
uv run --project /path/to/ionet-ai --extra mcp ionet-ai serve mcp
```

CLI examples:

```bash
uv run ionet-ai kb search "FlowContext"
uv run ionet-ai kb verify-upstream --fact artifact-version --coordinate com.iohao.net:run-one
uv run ionet-ai diagnose "generate an ionet Action feature"
uv run ionet-ai assemble "generate an ionet Action feature" --mode Generate
uv run ionet-ai validate-project --project /path/to/your-project
```

To install MCP runtime dependencies:

```bash
uv sync --extra mcp
```

## Training Source Boundary

The current maintainer-side training and distillation sources are:

- `ionet-doc`
- `ionet` source
- `ionet-examples` examples

Within `ionet-doc`, only the `docs/` directory and homepage body are valid text
sources for this knowledge base. Other directories must not be used for current
knowledge-base training, stable asset distillation, or generation flows.

These sources are for knowledge-base maintainers only. Regular local users only
need the current `ionet-ai` checkout; they do not need to have those training
sources.

Maintainer local checkouts are configured through source aliases in
`source-roots.yaml` and the untracked `.source-roots.local.yaml` override file.
Source anchors in knowledge assets should use the `alias:relative/path` form,
not local absolute paths.

## Directory Map

### Machine Entry Points

- `llms.txt`
  Minimal machine-readable entry point describing the default reading path,
  high-frequency intents, authoritative sources, and do-not-infer boundaries.
- `llms-full.txt`
  Fuller machine-readable public reading map for AI search and answer engines.
- `ai-index.yaml`
  Structured repository map for search, rerank, and agent routing.
- `ai-rules.yaml`
  Structured response boundaries covering reading priority, authority rules,
  response rules, and do-not-infer rules.

### `docs/`

High-level design, shared specifications, user installation and MCP startup
guides, task taxonomy, MCP tool contracts, and governance documents.

### `rules/`

Stable rule assets that answer what must be followed and which forms are
explicitly disallowed.

### `skill-defs/`

Task-family definition sources. Each `skill.yaml` defines assembly lists, task
classification, modes, and token budgets.

### `checklists/`

Repository-level quality-control checklists, including the topic coverage
matrix, high-frequency question regressions, and new knowledge-base bootstrap
checklists.

### `references/`

Fact-anchor layer that records upstream verification entry points, maintainer
source boundaries, source/document anchors, and starter evidence boundaries.

`references/` does not replace `rules/`, `stable/`, `skill-defs/`, or
`candidate/`, and it does not directly enter the main generation flow. Its main
role is answering where facts should be verified and what a given kind of
evidence can prove.

### `stable/`

Stable knowledge assets. Only `stable/` and `rules/` may enter the default main
design/generation flow.

Current subdirectories:

- `concepts/`
- `conventions/`
- `architecture-decisions/`
- `example-patterns/`
- `code-templates/`
- `checklists/`
- `api-contracts/`
- `anti-patterns/`
- `faq/`
- `source-policies/`

### `candidate/`

Candidate knowledge asset directory.

- May participate in search, diagnosis, explanation, review, and existing-code
  modification.
- Must not directly drive `Generate`.
- Must pass governance and human review before entering `stable/`.

### `assets/`

Local starter and example assets used to calibrate project structure, minimal
skeletons, and reviewable examples.

### `src/ionet_ai/`

Local Python/uv CLI and MCP runtime. It directly reads this repository's machine
entry points, `docs/`, `rules/`, `stable/`, `candidate/`, `assets/`,
`skill-defs/`, `checklists/`, and `references/`.

## Current Assembly Order

The local runtime follows:

```text
user request
  -> ionet-ai skill
  -> ionet-ai MCP / CLI
  -> full-repository visible knowledge sources
  -> constrained context
```

The main generation flow still follows:

```text
pattern -> template -> generate -> checklist
```

It is also constrained by:

- Only `stable/` may enter the main generation flow.
- `candidate/` must not directly drive generation.
- `anti-hallucination-rules` and `source-scope-rules` have high priority.
- When no stable pattern exists, downgrade to `Design` or `Explain`.

## Recommended Reading Order

1. [llms.txt](llms.txt)
2. [ai-rules.yaml](ai-rules.yaml)
3. [ai-index.yaml](ai-index.yaml)
4. [docs/architecture-summary.md](docs/architecture-summary.md)
5. [docs/ionet-ai-v1-design.md](docs/ionet-ai-v1-design.md)
6. [docs/asset-metadata-schema.md](docs/asset-metadata-schema.md)
7. [docs/task-taxonomy-map.md](docs/task-taxonomy-map.md)
8. [docs/knowledge-engineering-playbook.md](docs/knowledge-engineering-playbook.md)
9. [docs/mcp-tool-spec.md](docs/mcp-tool-spec.md)
10. [docs/mcp-assembly-validation-scenarios.md](docs/mcp-assembly-validation-scenarios.md)
11. [docs/knowledge-contract-audit.md](docs/knowledge-contract-audit.md)
12. [docs/user-installation.md](docs/user-installation.md)
13. [docs/asset-governance.md](docs/asset-governance.md)
14. [docs/candidate-source-analysis.md](docs/candidate-source-analysis.md)
15. [docs/candidate-promotion-checklist.md](docs/candidate-promotion-checklist.md)

Then continue to:

- [rules](rules)
- [skill-defs](skill-defs)
- [stable](stable)
- [candidate](candidate)
- [checklists](checklists)
- [references](references)

## Validation Commands

```bash
PYTHONPATH=src python3 -m ionet_ai kb search "FlowContext" --limit 3
PYTHONPATH=src python3 -m ionet_ai diagnose "generate an ionet Action feature"
PYTHONPATH=src python3 -m ionet_ai assemble "generate an ionet Action feature" --mode Generate
bash scripts/check-mcp-assembly-scenarios.sh
bash scripts/check-rule-contracts.sh
bash scripts/check-one-application-consistency.sh
bash scripts/check-agents-consistency.sh
bash scripts/check-ai-routing-assets.sh
bash scripts/check-candidate-promotion-ledger.sh
bash scripts/check-upstream-verifier.sh
```

`scripts/check-rule-contracts.sh` is the full Markdown knowledge-contract audit:
it checks metadata, skill asset references, rule assembly, source anchors, and
known generated-code drift patterns. Maintainer source checks resolve
`source-roots.yaml` aliases through `.source-roots.local.yaml` or environment
variables such as `IONET_ROOT`.

## Current Status

- Overall design documents, shared objects, and task-taxonomy documents have
  been established.
- Core rule, pattern, template, checklist, anti-pattern, FAQ, and source-policy
  assets have been established.
- `candidate/source-analysis/` is now a review-only candidate lane.
- Version-sensitive upstream facts have a narrow `kb verify-upstream` entry
  point for Maven/Sonatype artifact and GitHub release/tag live verification;
  JDK/Maven requirements still rely on manual upstream documentation review.
- The local Python/uv CLI and MCP runtime are the default runtime entry points.
- `skill-defs/` contains 10 task definitions: 6 core Generate/Design/Review
  task specifications and 4 definitions covering installation, ionet project
  setup, framework extension generation, and knowledge-engineering methods.
- `llms.txt`, `ai-index.yaml`, `ai-rules.yaml`, `checklists/`, and
  `references/` have been established for routing, authority boundaries,
  coverage matrices, regression questions, and fact anchors.
- The repository defaults to complete local checkout usage only.

## Next Directions

- Converge internal maintainer release criteria and execution progress through
  [checklists/internal-maintainer-release-readiness.md](checklists/internal-maintainer-release-readiness.md)
  and
  [checklists/internal-maintainer-release-progress.md](checklists/internal-maintainer-release-progress.md).
- Continue expanding narrow `stable/` pattern/template/checklist chains.
- Continue distilling high-value candidate notes into stable assets.
- Continue stress-testing each task family assembly result with
  `ionet-ai assemble`.
- Keep the local installation path simple and prioritize the complete local
  checkout installation model.