version: 1
purpose: >
  Structured retrieval, authority, and answer-boundary rules for AI systems
  loading the local ionet-ai repository.

read_priority:
  - llms.txt
  - llms-full.txt
  - ai-rules.yaml
  - ai-index.yaml
  - SKILL.md
  - README.md
  - docs/task-taxonomy-map.md
  - docs/knowledge-engineering-playbook.md
  - docs/ai-discovery.md
  - stable/conventions/constrained-kb-authority-routing-convention.md
  - stable/checklists/constrained-kb-bootstrap-readiness-checklist.md
  - references/README.md

authority:
  installation:
    use_paths:
      - skill-defs/install-and-use/skill.yaml
      - README.md
      - docs/user-installation.md
      - rules/source-scope-rules.md
    for_topics:
      - local install
      - MCP configuration
      - CLI launcher
      - non-local install path
  ionet_project_setup:
    use_paths:
      - skill-defs/ionet-project-setup/skill.yaml
      - stable/faq/ionet-framework-installation-boundary-faq.md
      - stable/faq/current-version-selection-boundary-faq.md
      - stable/faq/ionet-runtime-vm-options-faq.md
      - stable/faq/ionet-cookbook-example-boundary-faq.md
      - stable/faq/quick-zero-demo-version-sensitive-boundary-faq.md
      - stable/checklists/ionet-project-setup-checklist.md
      - references/upstream-fact-sources.md
      - references/source-anchor-map.md
    for_topics:
      - ionet framework install
      - ionet project setup
      - JDK and Maven setup
      - IDEA VM options
      - Agrona UnsafeApi startup failure
      - Maven dependency coordinate
      - cookbook example selection
      - quick-zero demo setup
  generation:
    use_paths:
      - rules
      - stable
      - skill-defs
    for_topics:
      - Generate
      - template binding
      - stable pattern selection
      - output checklist
  candidate:
    use_paths:
      - candidate
      - docs/candidate-source-analysis.md
      - docs/candidate-promotion-checklist.md
      - stable/source-policies/candidate-source-distillation-policy.md
      - stable/checklists/candidate-source-distillation-checklist.md
      - stable/faq/candidate-source-analysis-generate-boundary-faq.md
      - stable/faq/candidate-distillation-promotion-faq.md
      - stable/architecture-decisions/candidate-source-analysis-generate-boundary-decision.md
      - stable/anti-patterns/candidate-source-misuse-review-anti-pattern.md
      - stable/anti-patterns/candidate-note-wholesale-promotion-anti-pattern.md
    for_topics:
      - explain
      - review
      - diagnose
      - source analysis
      - modify existing code evidence
      - Generate exclusion boundary
      - candidate promotion boundary
  starters:
    use_paths:
      - assets
      - references/starter-evidence-map.md
    for_topics:
      - starter selection
      - inspectable examples
      - local project shape
      - starter evidence boundary
  references:
    use_paths:
      - references
    for_topics:
      - upstream verification entrypoints
      - maintainer source boundaries
      - source anchor lookup
      - starter evidence boundaries
      - local snapshot evidence boundaries
  knowledge_engineering:
    use_paths:
      - stable/conventions/constrained-kb-authority-routing-convention.md
      - stable/checklists/constrained-kb-bootstrap-readiness-checklist.md
      - stable/faq/repository-training-not-fine-tuning-faq.md
      - skill-defs/knowledge-engineering-method/skill.yaml
      - docs/knowledge-engineering-playbook.md
      - checklists/new-kb-bootstrap-checklist.md
      - checklists/topic-coverage-matrix.md
      - checklists/high-frequency-question-regression.md
    for_topics:
      - start a new knowledge base
      - knowledge engineering mechanism
      - coverage planning
      - regression planning
  version_sensitive_facts:
    use_paths:
      - references/upstream-fact-sources.md
      - references/source-anchor-map.md
      - stable/faq/current-version-selection-boundary-faq.md
      - stable/source-policies/upstream-version-fact-verification-policy.md
      - stable/source-policies/ionet-doc-stable-source-scope-policy.md
      - rules/source-scope-rules.md
      - checklists/topic-coverage-matrix.md
      - checklists/high-frequency-question-regression.md
    for_topics:
      - latest ionet version
      - current ionet release
      - JDK requirement
      - Maven Central version
      - dependency version
      - release tag

response_rules:
  - Keep ionet terms stable: External Server, Logic Server, Action, FlowContext, OneApplication.
  - For public concept wording, prefer official ionet terms such as Action, main route, sub-route, FlowContext, ExternalServer, and LogicServer before translating to generic web analogies.
  - Prefer stable rules and stable assets before generating or modifying code.
  - Prefer starter-aware answers when the task asks for project structure or runnable skeletons.
  - State downgrade reasons when stable pattern or template support is missing.
  - Use checklists to describe quality gates instead of inventing informal review criteria.
  - For project-structure example questions, use examples as role calibration and reject copied demo-only layout or tooling details.
  - For SDK target-language pages, use them as client integration evidence only; do not generate SDK or frontend project files by default.
  - For quick-zero demo setup, treat dependency versions, Java versions, ports, JAR names, console output, and example paths as snapshot evidence unless verified.
  - For new knowledge bases, describe knowledge engineering as routing, authority, coverage, and regression design, not model fine-tuning.
  - For latest/current version, JDK, dependency, Maven Central, or release questions, require upstream verification or label local evidence as a snapshot.
  - Do not produce version-pinned generated code unless the version was verified upstream or supplied by the user.
  - Keep ionet framework setup separate from ionet-ai repository installation; use ionet-project-setup for framework dependency, VM option, Maven, and cookbook questions.
  - Use references for fact anchors and source verification entrypoints, but never as Generate pattern or template authority.
  - For candidate source-analysis boundary questions, answer from stable boundary assets first and only use candidate notes as evidence for allowed explain, review, diagnose, or modify-existing tasks.

do_not_infer:
  - candidate source-analysis assets as direct Generate pattern or template input
  - latest upstream release facts from this repository alone
  - current JDK, dependency, Maven Central, or release facts from cached local docs alone
  - non-local artifacts as the current install path
  - generic Java Web or Spring MVC structure as ionet default structure
  - examples or starter code as stable rules unless the rule is also present under rules or stable
  - SDK target-language setup as default server-side project structure
  - quick-zero demo version, port, JAR, console, or example path details as current defaults
  - references as stable Generate patterns, templates, or candidate promotion decisions
  - weak or partial coverage as complete support without downgrade wording

task_redirects:
  install:
    - skill-defs/install-and-use/skill.yaml
    - README.md
    - docs/user-installation.md
  ionet_project_setup:
    - skill-defs/ionet-project-setup/skill.yaml
    - stable/faq/ionet-framework-installation-boundary-faq.md
    - stable/faq/current-version-selection-boundary-faq.md
    - stable/faq/ionet-runtime-vm-options-faq.md
    - stable/faq/ionet-cookbook-example-boundary-faq.md
    - stable/faq/quick-zero-demo-version-sensitive-boundary-faq.md
    - stable/checklists/ionet-project-setup-checklist.md
    - references/upstream-fact-sources.md
    - references/source-anchor-map.md
  client_sdk_integration:
    - skill-defs/design-interaction-contract/skill.yaml
    - stable/faq/client-sdk-target-setup-boundary-faq.md
    - stable/faq/client-sdk-example-generation-boundary-faq.md
    - stable/example-patterns/client-integration-contract-pattern.md
    - stable/checklists/client-integration-contract-checklist.md
    - stable/checklists/proto-codegen-boundary-checklist.md
    - references/source-anchor-map.md
  action_generation:
    - skill-defs/generate-action-feature/skill.yaml
    - rules/action-rules.md
    - stable/example-patterns/action-entry-pattern.md
    - stable/code-templates/action-entry-template.md
    - stable/faq/ionet-example-evidence-calibration-faq.md
    - stable/api-contracts/action-method-signature-api-contract.md
    - stable/api-contracts/data-codec-api-contract.md
    - stable/checklists/protocol-fragment-boundary-checklist.md
    - stable/faq/protocol-fragment-boundary-faq.md
    - checklists/high-frequency-question-regression.md
    - stable/checklists/generate-action-feature-checklist.md
  project_structure_examples:
    - references/starter-evidence-map.md
    - references/ionet-examples-evidence-map.md
    - rules/project-structure-rules.md
    - stable/concepts/quick-start-structure-concept.md
    - stable/faq/quick-start-example-copy-boundary-faq.md
    - stable/faq/ionet-example-evidence-calibration-faq.md
    - stable/anti-patterns/example-overfit-generation-anti-pattern.md
    - checklists/high-frequency-question-regression.md
  public_concept_wording:
    - stable/conventions/ionet-role-vocabulary-convention.md
    - stable/concepts/action-entry-concept.md
    - stable/concepts/interaction-contract-concept.md
    - stable/concepts/flow-context-runtime-concept.md
    - stable/concepts/communication-model-concept.md
    - stable/concepts/external-server-boundary-concept.md
    - stable/concepts/logic-server-boundary-concept.md
    - checklists/high-frequency-question-regression.md
  runtime_flow:
    - skill-defs/design-runtime-flow/skill.yaml
    - rules/flow-context-rules.md
    - stable/concepts/flow-context-runtime-concept.md
    - stable/faq/flow-context-real-request-boundary-faq.md
    - stable/checklists/flow-context-runtime-scenario-checklist.md
    - stable/example-patterns/flow-context-broadcast-pattern.md
    - stable/api-contracts/data-codec-api-contract.md
    - stable/api-contracts/taskkit-api-contract.md
    - stable/api-contracts/delay-taskkit-api-contract.md
    - stable/api-contracts/delay-task-api-contract.md
    - stable/api-contracts/property-listener-api-contract.md
    - stable/api-contracts/websocket-verify-api-contract.md
    - stable/checklists/taskkit-scheduling-boundary-checklist.md
    - docs/flow-context-rule-examples.md
    - checklists/high-frequency-question-regression.md
  external_server_builder:
    - skill-defs/generate-framework-implementation/skill.yaml
    - rules/external-server-generation-rules.md
    - rules/naming-rules.md
    - stable/concepts/external-server-boundary-concept.md
    - stable/conventions/framework-extension-naming-convention.md
    - stable/example-patterns/framework-implementation-naming-pattern.md
    - stable/code-templates/framework-implementation-template.md
    - stable/api-contracts/external-server-builder-api-contract.md
    - stable/api-contracts/external-server-hooks-api-contract.md
    - stable/api-contracts/on-external-api-contract.md
    - stable/api-contracts/access-authentication-api-contract.md
    - stable/checklists/external-communication-boundary-checklist.md
    - checklists/high-frequency-question-regression.md
  one_application:
    - skill-defs/design-server-boundary/skill.yaml
    - rules/one-application-rules.md
    - stable/concepts/one-application-boundary-concept.md
    - stable/example-patterns/one-application-pattern.md
    - stable/code-templates/one-application-template.md
    - stable/checklists/one-application-checklist.md
    - stable/anti-patterns/one-application-overreach-anti-pattern.md
    - checklists/high-frequency-question-regression.md
  review:
    - skill-defs/review-ionet-code/skill.yaml
    - skill-defs/modify-existing-ionet-code/skill.yaml
    - docs/candidate-source-analysis.md
    - docs/asset-governance.md
    - stable/checklists/review-ionet-code-checklist.md
    - stable/checklists/modify-existing-impact-checklist.md
    - stable/checklists/action-command-lookup-modification-checklist.md
    - stable/checklists/message-field-compatibility-checklist.md
    - stable/checklists/protocol-visible-change-checklist.md
    - stable/concepts/protocol-visible-route-change-concept.md
    - checklists/high-frequency-question-regression.md
  candidate_source_boundary:
    - docs/candidate-source-analysis.md
    - docs/candidate-promotion-checklist.md
    - stable/source-policies/candidate-source-distillation-policy.md
    - stable/checklists/candidate-source-distillation-checklist.md
    - stable/faq/candidate-source-analysis-generate-boundary-faq.md
    - stable/faq/candidate-distillation-promotion-faq.md
    - stable/faq/modify-existing-downgrade-boundary-faq.md
    - stable/architecture-decisions/candidate-source-analysis-generate-boundary-decision.md
    - stable/anti-patterns/candidate-source-misuse-review-anti-pattern.md
    - stable/anti-patterns/candidate-note-wholesale-promotion-anti-pattern.md
    - checklists/high-frequency-question-regression.md
  coverage_downgrade:
    - checklists/topic-coverage-matrix.md
    - checklists/high-frequency-question-regression.md
    - stable/conventions/constrained-kb-authority-routing-convention.md
    - stable/checklists/constrained-kb-bootstrap-readiness-checklist.md
  knowledge_engineering:
    - skill-defs/knowledge-engineering-method/skill.yaml
    - stable/conventions/constrained-kb-authority-routing-convention.md
    - stable/checklists/constrained-kb-bootstrap-readiness-checklist.md
    - stable/faq/repository-training-not-fine-tuning-faq.md
    - docs/knowledge-engineering-playbook.md
    - checklists/new-kb-bootstrap-checklist.md
    - checklists/topic-coverage-matrix.md
    - checklists/high-frequency-question-regression.md
  version_sensitive_facts:
    - references/upstream-fact-sources.md
    - references/source-anchor-map.md
    - stable/source-policies/upstream-version-fact-verification-policy.md
    - stable/source-policies/ionet-doc-stable-source-scope-policy.md
    - rules/source-scope-rules.md
    - checklists/topic-coverage-matrix.md
    - checklists/high-frequency-question-regression.md