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 for crawler policy and search-engine submission notes.

Local Installation

Run this from the repository root:

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:

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

CLI examples:

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:

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:

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

The main generation flow still follows:

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

Then continue to:

• rules
• skill-defs
• stable
• candidate
• checklists
• references

Validation Commands

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 and 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.