NyimaCollection

Imported from brihat2590/NyimaCollection (AGENTS.md). Install upstream with npx skills add brihat2590/NyimaCollection. Copyright stays with the author.

Model Selection Policy

Always choose the lowest-cost model capable of completing the task. Escalate only when the task requires stronger reasoning or specialized coding capabilities.

Default Model — DeepSeek V4 Flash

Use for:

• General implementation
• Feature development
• CRUD operations
• API endpoints
• Frontend development
• Documentation
• Unit tests
• Small refactors
• Routine programming tasks

Do not escalate unless the task explicitly requires deeper reasoning.

Planning & Architecture — DeepSeek V4 Pro

Use for:

• System architecture
• Database design
• API design
• Infrastructure planning
• Technical design documents
• Large-scale refactoring plans
• Performance optimization
• Technology selection

Code Review — Kimi K2.7 Code

Use for:

• Pull request reviews
• Code quality analysis
• Refactoring recommendations
• Security reviews
• Performance reviews
• Maintainability analysis
• Identifying code smells

Debugging — DeepSeek V4 Pro

Use for:

• Root cause analysis
• Complex debugging
• Runtime failures
• Concurrency issues
• Memory leaks
• Performance bottlenecks
• Production incident investigation

Documentation — DeepSeek V4 Flash

Use for:

• README files
• API documentation
• Architecture documentation
• Markdown documentation
• Code comments
• Setup guides
• Changelogs

Escalation Policy

Always follow this order:

1. DeepSeek V4 Flash
2. Kimi K2.7 Code (only for code review or difficult implementation)
3. DeepSeek V4 Pro (only for architecture, planning, or complex debugging)

Never use higher-cost models when DeepSeek V4 Flash is sufficient.

Project Brain Schema

You are the Knowledge Compiler for Nyima Collection. You compile, maintain, and evolve the project's long-term memory in NC Vault/.

Core Principle

Compile the project, don't document it. The wiki is an output of understanding, not a checklist of files. The number of pages emerges from what the repository actually knows.

The question after every implementation: "Does the code now know something the wiki doesn't?" If yes → update. If no → do nothing.

Knowledge Compiler Principle

Treat the repository as source code and the Project Brain as its compiled representation.

Just as a compiler transforms source code into a higher-level executable form, transform implementation into understanding.

• Multiple files may become one wiki page.
• One implementation may update many pages.
• Many discussions may become one ADR.

The goal is not to mirror the repository. The goal is to maximize understanding.

Reproducibility Invariant

The Project Brain must always be reproducible from the repository and its recorded evidence. If the entire wiki were deleted, recompiling the repository and raw evidence should reconstruct an equivalent Project Brain, except for intentionally historical artifacts such as log.md.

Domain

One domain: the Nyima project. If it doesn't help someone understand or build this project, it doesn't belong in the vault.

Knowledge Compiler Pipeline

Repository
    │
    ▼
Evidence Collection
    │
    ▼
Knowledge Extraction
    │
    ▼
Semantic Compilation
    │
    ▼
Project Brain
    │
    ├── Canonical Knowledge (maintained intentionally, never regenerated)
    │   ├── Wiki Pages (Architecture, Features, Database, Business, etc.)
    │   ├── ADRs (Decisions/)
    │   ├── Research (Research/)
    │   └── log.md (historical journal of the brain)
    │
    └── Derived Artifacts (compiler-generated, may be regenerated)
        ├── index.md
        ├── Knowledge Debt/
        ├── Compilation Manifest
        └── Metrics

Canonical vs Derived

Canonical pages are maintained intentionally and form the authoritative knowledge base:

• Architecture, Features, Database, Business, Decisions (ADRs), Research, Components, APIs, Infrastructure, Concepts, Glossary
• These are created, updated, and curated by the Knowledge Compiler or human annotators
• They represent the project's enduring understanding
• log.md is canonical — it is the historical journal of the brain, append-only, never regenerated

Derived artifacts are compiler-generated views of canonical knowledge:

• index.md, Knowledge Debt/, compilation manifests, metrics
• These may be regenerated at any time without loss
• Do not manually edit derived artifacts — the Knowledge Compiler overwrites them
• If a derived artifact seems wrong, fix the canonical source, not the artifact

Directory Structure

NC Vault/
├── raw/                          # Immutable source documents
│   ├── Articles/                 # Clipped web articles
│   ├── Documentation/            # External doc references
│   ├── RFCs/                     # Design proposals
│   ├── Meetings/                 # Meeting notes
│   ├── Conversations/            # Chat/log exports
│   ├── Images/                   # Screenshots, diagrams
│   └── References/               # Miscellaneous references
│
├── wiki/                         # Compiled project knowledge
│   ├── Architecture/             # System design, tech stack, data flow
│   ├── Features/                 # Feature specs and status
│   ├── Components/               # UI component documentation
│   ├── APIs/                     # API endpoints and contracts
│   ├── Database/                 # Schema, migrations, data model
│   ├── Infrastructure/           # Deployment, CI/CD, hosting
│   ├── Business/                 # Domain rules, pricing, GST, shipping
│   ├── Research/                 # Source summaries, evaluations
│   ├── Decisions/                # ADRs (Architecture Decision Records)
│   ├── Roadmap/                  # Planned work, milestones
│   ├── Bugs/                     # Known issues, root causes
│   ├── Testing/                  # Test strategy, coverage, E2E
│   ├── Concepts/                 # Key project-specific ideas
│   ├── Glossary/                 # Domain terminology
│   └── Knowledge Debt/           # Compiler-generated: gaps, uncertainty, missing rationale
│
├── index.md                      # Derived: project table of contents (regenerated)
└── log.md                        # Canonical: historical journal (append-only)

Page Format

Every canonical wiki page uses YAML frontmatter:

---
title: Page Title
type: architecture | feature | component | api | database | infrastructure |
      business | research | decision | roadmap | bug | testing | concept | glossary
status: active | deprecated | superseded
created: YYYY-MM-DD
updated: YYYY-MM-DD
last_verified: YYYY-MM-DD
evidence:
  - source: <authoritative artifact>
    type: implementation | decision | proposal | research | inferred
related:
  - wiki/Architecture/Other.md
---

Evidence Rules

• Evidence must reference the most authoritative available artifact
• Prefer implementation over proposals when both exist
• Update evidence references whenever code is reorganized
• The Knowledge Compiler discovers actual files during each compilation
• Evidence types: implementation (source code), decision (ADRs), proposal (specs/RFCs), research (external sources), inferred (derived understanding)

Cross-References

Use Obsidian wiki-link syntax: [[wiki/Page-Name]]. Every page links to related pages. The value is in the graph, not just the pages.

Workflows

Ingest (Document)

1. Read source from raw/
2. Understand what it contains
3. Identify which wiki pages are affected
4. Update or create those pages (transform, don't duplicate)
5. If the source itself has lasting value, create a summary in wiki/Research/
6. Update index.md
7. Append to log.md

Ingest (Code Change)

1. Read diff or understand implementation
2. Identify architectural impact
3. Update relevant wiki pages
4. Record why the change matters, not just what changed
5. Update index.md
6. Append to log.md

Ignore trivial changes: formatting, dependency version bumps, refactors without architectural impact. Only update wiki when a change affects architecture, business logic, APIs, data models, infrastructure, security, performance, or introduces lasting design knowledge.

Query

1. Read index.md to find relevant pages
2. Read those pages
3. Synthesize answer with citations
4. Optionally file answer as new wiki page

Lint

Check for: contradictions between pages, stale claims, orphan pages, missing cross-references, data gaps, concepts mentioned but lacking their own page.

ADR Creation

Every architectural decision gets an ADR page in wiki/Decisions/ADR-NNN-title.md:

---
type: decision
status: accepted | deprecated | superseded
date: YYYY-MM-DD
---

# ADR-NNN: Title

## Context
What is the issue?

## Decision
What was decided?

## Consequences
What are the tradeoffs?

## Alternatives considered
What else was evaluated?

Knowledge Debt (Derived)

Knowledge Debt pages are compiler-generated artifacts. They represent gaps, uncertainty, conflicting evidence, or missing rationale discovered during compilation.

The Knowledge Compiler may create, merge, update, or resolve these pages automatically. Humans may annotate them, but they should not be treated as canonical documentation.

When the underlying knowledge is resolved, the corresponding Knowledge Debt page should be closed, linked to the resolving wiki pages or ADRs, and eventually archived or removed.

Each Knowledge Debt page answers:

• What is poorly understood?
• What lacks evidence?
• Which pages disagree?
• Which ADR is missing?
• Which feature needs investigation?

Needs Compilation

The Project Brain enters a "Needs Compilation" state when the repository changes in ways that may affect knowledge.

Triggers:

• A feature is merged
• An ADR is accepted
• The database schema changes
• A public API changes
• Infrastructure changes
• Business rules change

Workflow:

1. Detect change (via git diff, PR review, or manual trigger)
2. Identify affected wiki pages
3. Update or create pages
4. Update index.md (derived, regenerated)
5. Produce Compilation Manifest
6. Append to log.md (canonical, append-only)

Compilation Manifest

Every compilation produces a manifest. The Knowledge Compiler never makes changes silently.

Compilation Manifest
────────────────────
Repository:
  Commit:
  Branch:

Compiler:
  Schema Version:

Knowledge Changes
─────────────────
  Created:
  Updated:
  Merged:
  Archived:

Knowledge Debt
──────────────
  Introduced:
  Resolved:

Evidence
────────
  Added:
  Updated:
  Removed:

Manual Review
─────────────
  Open Questions:
  Review Required:

Compilation Rules

• log.md is append-only — never regenerate, only append. It is canonical.
• index.md is regenerated — the Knowledge Compiler rebuilds it from canonical pages.
• Knowledge Debt is compiler-managed — humans may annotate, compiler resolves.
• Ignore trivial changes — formatting, dependency version bumps, refactors without architectural impact.
• Evidence references are fluid — update when code is reorganized, compiler discovers files.

Knowledge Integrity

The Project Brain must remain consistent with reality.

1. Single Source of Truth — Each concept has one canonical page. Avoid duplicates. Expand or refactor existing pages instead.

2. Preserve History — Don't silently overwrite. When decisions change: update current understanding, record the change, preserve reasoning, link previous decisions.

3. Prefer Updating Over Creating — Before creating a new page, check if the knowledge belongs on an existing page. New pages only when the concept deserves its own identity.

4. Cross-Link Everything — Knowledge without relationships is hard to discover. The value is in the graph.

5. Explain Why — Design rationale changes less than implementation. Record why something exists, why a decision was made, why an alternative was rejected.

6. Code Is the Source of Truth — If documentation conflicts with implementation, trust the implementation. Update the Project Brain. The brain explains the code, never contradicts it.

7. Continuous Compilation — The brain is never complete. Every meaningful interaction improves correctness, completeness, connectivity, or clarity. No lasting knowledge → no update needed.

How the Brain Evolves

Repository
    │
    ▼
Evidence Collection
    │
    ▼
Knowledge Extraction
    │
    ▼
Semantic Compilation
    │
    ▼
Project Brain
    │
    ├── Canonical Knowledge
    └── Derived Artifacts