version: 1
repo:
  name: ionet-ai
  type: local-first-constrained-knowledge-base
  summary: >
    Local ionet knowledge base with governed stable assets, candidate review lanes,
    task definitions, starter assets, CLI/MCP runtime access, and quality checklists.

machine_entrypoints:
  primary:
    - path: llms.txt
      role: smallest machine bootstrap and routing summary
    - path: llms-full.txt
      role: fuller public reading map for AI search and answer engines
    - path: ai-rules.yaml
      role: structured answer-boundary and authority rules
    - path: ai-index.yaml
      role: structured repository manifest and task bundle map
    - path: SKILL.md
      role: agent-facing routing rules and answer constraints
    - path: README.md
      role: repository overview and default reading path
    - path: docs/knowledge-engineering-playbook.md
      role: reusable method for starting new constrained knowledge bases
    - path: docs/ai-discovery.md
      role: public Pages, robots, sitemap, and AI crawler notes
    - path: stable/conventions/constrained-kb-authority-routing-convention.md
      role: stable authority routing method for constrained knowledge bases
    - path: stable/checklists/constrained-kb-bootstrap-readiness-checklist.md
      role: stable bootstrap readiness gate for constrained knowledge bases
    - path: references/README.md
      role: fact-anchor layer for upstream verification and evidence boundaries

layers:
  - id: docs
    path: docs
    role: architecture, installation, task taxonomy, governance, and explanations
  - id: rules
    path: rules
    role: stable mandatory rules and negative constraints
  - id: stable
    path: stable
    role: stable generation, review, explanation, and API contract assets
  - id: candidate
    path: candidate
    role: candidate review lane, source analysis, search, and diagnosis evidence
  - id: assets
    path: assets
    role: starter assets and inspectable examples
  - id: skill-defs
    path: skill-defs
    role: task family definitions and context assembly source
  - id: checklists
    path: checklists
    role: coverage, regression, bootstrap, and quality controls
  - id: references
    path: references
    role: fact anchors, upstream verification entrypoints, maintainer source boundaries, and starter evidence boundaries

task_bundles:
  - id: install-and-use
    when:
      - install ionet-ai
      - configure MCP
      - use local knowledge base
      - non-local install path
    open:
      - skill-defs/install-and-use/skill.yaml
      - README.md
      - docs/user-installation.md
  - id: ionet-project-setup
    when:
      - install ionet framework
      - ionet project setup
      - IDEA VM options
      - Agrona UnsafeApi error
      - Maven dependency setup
      - current ionet dependency version
      - JDK version today
      - cookbook examples
      - quick-zero demo
      - ionet quick demo
    open:
      - 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
      - checklists/high-frequency-question-regression.md
  - id: client-sdk-integration
    when:
      - client SDK setup
      - iohao-sdk
      - TypeScript SDK
      - C# SDK
      - GDScript SDK
      - Godot SDK
      - Unity SDK
      - Vue SDK
      - Cocos SDK
      - non-SDK frontend example
      - client integration impact
    open:
      - 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/example-patterns/proto-codegen-boundary-pattern.md
      - stable/checklists/proto-codegen-boundary-checklist.md
      - references/source-anchor-map.md
      - checklists/high-frequency-question-regression.md
  - id: knowledge-engineering-method
    when:
      - train a new knowledge base
      - build a constrained knowledge base
      - summarize knowledge engineering mechanisms
      - repository training not fine-tuning
    open:
      - 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
  - id: version-sensitive-facts
    when:
      - latest ionet version
      - current ionet release
      - JDK requirement
      - Maven Central version
      - dependency version
      - release tag
    open:
      - references/upstream-fact-sources.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
  - id: action-generation
    when:
      - generate Action
      - add ionet feature
      - create cmd subCmd flow
      - Action generation examples
      - Action primitive parameter
      - Action List return
      - protocol fragment
    open:
      - 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/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
      - stable/checklists/generate-action-feature-checklist.md
      - stable/faq/ionet-example-evidence-calibration-faq.md
      - checklists/high-frequency-question-regression.md
  - id: project-structure-examples
    when:
      - project structure
      - quick-start examples
      - starter shape
      - ionet-examples project structure
    open:
      - 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
  - id: public-concept-wording
    when:
      - public ionet concepts
      - what is Action
      - Cmd subCmd
      - ExternalServer LogicServer
      - official API wording
    open:
      - 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
  - id: runtime-flow
    when:
      - FlowContext
      - broadcast
      - cross process call
      - runtime flow
      - FlowContext broadcast design
      - design a FlowContext broadcast flow
      - request multiple response
      - callCollect
      - OnExternal
      - callExternal
      - ExternalServer extension
      - WebSocket verify
      - WebSocket token verification
      - AccessAuthenticationHook
      - route access authentication
      - ExternalServer cache
      - CmdCacheOption
      - JSR380 validation
      - ValidatorKit
      - property listener
      - BooleanProperty
      - LongProperty
      - DataCodec
      - DataCodecManager
      - JSON codec
      - protocol fragment
      - delayed task
      - cancel delayed task
      - TaskListener
      - IntervalTaskListener
      - CommunicationKit broadcast API
      - room operation
      - OperationHandler
      - Domain Event
      - EventBus
    open:
      - 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/delay-taskkit-api-contract.md
      - stable/api-contracts/delay-task-api-contract.md
      - stable/api-contracts/taskkit-api-contract.md
      - stable/api-contracts/communication-kit-api-contract.md
      - stable/concepts/request-multiple-response-concept.md
      - stable/api-contracts/communication-logic-collect-api-contract.md
      - stable/example-patterns/request-multiple-response-collect-pattern.md
      - stable/concepts/on-external-extension-concept.md
      - stable/api-contracts/external-communication-api-contract.md
      - stable/api-contracts/on-external-api-contract.md
      - stable/api-contracts/websocket-verify-api-contract.md
      - stable/concepts/access-authentication-boundary-concept.md
      - stable/api-contracts/access-authentication-api-contract.md
      - stable/concepts/external-cmd-cache-boundary-concept.md
      - stable/api-contracts/external-cmd-cache-api-contract.md
      - stable/concepts/parameter-validation-boundary-concept.md
      - stable/api-contracts/parameter-validation-api-contract.md
      - stable/concepts/property-listener-runtime-concept.md
      - stable/api-contracts/property-listener-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
      - stable/checklists/taskkit-scheduling-boundary-checklist.md
      - stable/checklists/external-access-and-cache-boundary-checklist.md
      - stable/checklists/action-parameter-validation-checklist.md
      - stable/checklists/property-listener-runtime-checklist.md
      - stable/example-patterns/on-external-extension-pattern.md
      - stable/checklists/external-communication-boundary-checklist.md
      - stable/concepts/event-bus-runtime-concept.md
      - stable/api-contracts/event-bus-api-contract.md
      - stable/example-patterns/event-bus-publish-subscribe-pattern.md
      - stable/checklists/event-bus-runtime-checklist.md
      - stable/concepts/domain-event-runtime-concept.md
      - stable/api-contracts/domain-event-api-contract.md
      - stable/example-patterns/domain-event-handler-pattern.md
      - stable/faq/domain-event-vs-event-bus-faq.md
      - stable/api-contracts/room-operation-api-contract.md
      - stable/example-patterns/room-operation-handler-pattern.md
      - stable/code-templates/room-operation-handler-template.md
      - docs/flow-context-rule-examples.md
      - assets/multi-process-ionet-starter/README.md
      - checklists/high-frequency-question-regression.md
  - id: external-server-builder
    when:
      - ExternalServer builder
      - ExternalServer helper
      - create external server
      - custom external server
      - 对外服
      - 自定义对外服
      - 游戏对外服
      - MyExternalServer
    open:
      - 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
  - id: framework-extensions
    when:
      - DebugInOut
      - StatActionInOut
      - ThreadMonitorInOut
      - TimeRangeInOut
      - InOut plugin
      - Spring integration
      - ActionFactoryBeanForSpring
      - core plugin
      - action statistics plugin
    open:
      - skill-defs/design-server-boundary/skill.yaml
      - stable/conventions/inout-plugin-observability-convention.md
      - stable/api-contracts/inout-plugin-api-contract.md
      - stable/example-patterns/inout-plugin-observability-boundary-pattern.md
      - stable/checklists/inout-plugin-observability-checklist.md
      - stable/concepts/spring-action-factory-integration-concept.md
      - stable/api-contracts/spring-action-factory-api-contract.md
      - stable/faq/framework-extension-boundary-faq.md
      - stable/faq/framework-integration-defaults-faq.md
      - checklists/high-frequency-question-regression.md
  - id: external-protocol
    when:
      - ExternalMessage
      - custom external protocol
      - CommunicationMessageCodec
      - TCP external codec
      - WebSocket external protocol
    open:
      - stable/concepts/external-message-protocol-concept.md
      - stable/api-contracts/external-message-api-contract.md
      - stable/faq/external-message-customization-boundary-faq.md
      - stable/checklists/external-communication-boundary-checklist.md
      - stable/concepts/external-server-boundary-concept.md
      - checklists/high-frequency-question-regression.md
  - id: proto-and-codegen
    when:
      - generate proto
      - JProtobuf
      - ProtoFileMerge
      - generated document
      - client SDK generation
      - iohao-sdk
      - TypeScript SDK
      - C# SDK
      - GDScript SDK
      - DocumentHelper
      - BroadcastDocument
      - DocumentMethod
    open:
      - skill-defs/design-interaction-contract/skill.yaml
      - stable/conventions/proto-generation-convention.md
      - stable/api-contracts/proto-generation-api-contract.md
      - stable/api-contracts/document-codegen-api-contract.md
      - stable/example-patterns/proto-codegen-boundary-pattern.md
      - stable/code-templates/proto-codegen-boundary-note-template.md
      - stable/checklists/proto-codegen-boundary-checklist.md
      - stable/checklists/client-integration-contract-checklist.md
      - stable/faq/client-sdk-example-generation-boundary-faq.md
      - stable/faq/client-sdk-target-setup-boundary-faq.md
      - checklists/high-frequency-question-regression.md
  - id: one-application
    when:
      - OneApplication
      - RunOne
      - setLogicServerList
      - enableCenterServer
      - OneApplication startup chain
      - generate a OneApplication startup chain
    open:
      - 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
      - docs/one-application-acceptance-scenarios.md
      - checklists/high-frequency-question-regression.md
  - id: review-or-modify-existing
    when:
      - review ionet code
      - modify existing ionet code
      - explain source behavior
      - existing Action route change
      - Message field change
      - Action return type change
      - protocol-visible change
    open:
      - 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
  - id: candidate-source-boundary
    when:
      - candidate source analysis
      - candidate source analysis drive Generate
      - candidate note promotion
      - wholesale candidate promotion
      - ModifyExisting with candidate evidence
    open:
      - 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
  - id: coverage-downgrade
    when:
      - coverage gaps
      - weak coverage
      - partial coverage
      - downgrade answer
      - unsupported complete answer
    open:
      - 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

authority_rules:
  facts:
    use_paths:
      - references/upstream-fact-sources.md
      - references/source-anchor-map.md
      - docs/user-installation.md
      - skill-defs/install-and-use/skill.yaml
      - skill-defs/ionet-project-setup/skill.yaml
      - docs/architecture-summary.md
      - rules/source-scope-rules.md
      - stable/source-policies/upstream-version-fact-verification-policy.md
      - stable/faq/current-version-selection-boundary-faq.md
      - stable/faq/ionet-framework-installation-boundary-faq.md
      - stable/faq/ionet-runtime-vm-options-faq.md
    use_for:
      - local installation facts
      - ionet framework setup facts
      - repository runtime shape
      - source boundary
      - version-sensitive fact boundaries
      - fact verification entrypoints
  reference_anchors:
    use_paths:
      - references
    use_for:
      - upstream verification entrypoints
      - maintainer source boundaries
      - starter evidence boundaries
      - source anchor lookup
      - local snapshot boundary wording
  stable_generation:
    use_paths:
      - rules
      - stable
      - skill-defs
    use_for:
      - Generate
      - Review
      - ModifyExisting
  candidate_evidence:
    use_paths:
      - candidate
      - docs/candidate-source-analysis.md
      - stable/source-policies/candidate-source-distillation-policy.md
      - stable/faq/candidate-source-analysis-generate-boundary-faq.md
      - stable/architecture-decisions/candidate-source-analysis-generate-boundary-decision.md
      - stable/anti-patterns/candidate-note-wholesale-promotion-anti-pattern.md
    use_for:
      - search
      - diagnose
      - explain
      - review
      - modify-existing evidence
      - Generate exclusion boundary
      - promotion boundary
  quality_controls:
    use_paths:
      - checklists
    use_for:
      - coverage assessment
      - regression questions
      - new knowledge-base bootstrap
  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
    use_for:
      - new constrained knowledge-base training
      - repository training method
      - authority routing
      - bootstrap readiness
      - fine-tuning boundary
      - assemble context for knowledge-engineering questions

install:
  project_install: scripts/install-project.sh
  skill: skill-defs/install-and-use/skill.yaml
  user_guide: docs/user-installation.md

validation:
  assembly: scripts/check-mcp-assembly-scenarios.sh
  agents_consistency: scripts/check-agents-consistency.sh
  one_application: scripts/check-one-application-consistency.sh
  candidate_promotion: scripts/check-candidate-promotion-ledger.sh
  ai_routing_assets: scripts/check-ai-routing-assets.sh
  rule_contracts: scripts/check-rule-contracts.sh

non_goals:
  - not a broad ungoverned RAG dump
  - not a fine-tuned model
  - not a replacement for latest upstream release verification
  - not a non-local install path