@zigrivers/scaffold 3.27.0 → 3.29.0

package/content/knowledge/game/game-design-document.md

@@ -2,6 +2,10 @@
 name: game-design-document
 description: GDD structure, game pillars, core loop design, mechanics documentation, and progression archetypes
 topics: [game-dev, design, gdd, mechanics, progression]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 A Game Design Document (GDD) is the authoritative source of truth for what a game is, how it plays, and why its systems exist. Unlike traditional software requirements docs, a GDD must capture the feel and fantasy of the experience alongside its mechanical specifications. A well-structured GDD prevents scope creep, aligns the team on creative vision, and serves as the contract between design, engineering, and art.

package/content/knowledge/game/game-domain-patterns.md

@@ -2,6 +2,10 @@
 name: game-domain-patterns
 description: ECS vs DDD as mutually exclusive per-layer patterns, game state machines, and domain modeling for games
 topics: [game-dev, ecs, ddd, state-machines, domain-modeling]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game software architecture differs fundamentally from business software architecture because games have two distinct layers with incompatible optimization goals: the simulation layer (real-time, data-oriented, performance-critical) and the meta-game layer (behavior-rich, event-driven, correctness-critical). Choosing the right domain modeling approach for each layer is essential. ECS and DDD are mutually exclusive paradigms — applying the wrong one to a layer creates friction that compounds throughout development.

package/content/knowledge/game/game-economy-design.md

@@ -2,6 +2,10 @@
 name: game-economy-design
 description: Virtual currency design, faucet/sink balancing, loot table probability, monetization models, and ethical monetization patterns
 topics: [game-dev, economy, monetization, loot-tables, balance, f2p]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game economy design governs how players earn, spend, and value in-game resources and how the studio monetizes those systems. A well-designed economy creates meaningful choices — players decide what to spend resources on, creating engagement. A poorly designed economy either trivializes resources (inflation makes everything cheap) or frustrates players (everything feels unattainable). Monetization layers add a second dimension: real money must integrate with virtual economies without destroying the earned-value perception that makes the economy work.

package/content/knowledge/game/game-engine-selection.md

@@ -2,6 +2,10 @@
 name: game-engine-selection
 description: Engine evaluation framework, Unity vs Unreal vs Godot comparison, middleware selection, and platform considerations
 topics: [game-dev, engine, unity, unreal, godot, middleware]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Choosing a game engine is the single most consequential technical decision in game development. It determines your rendering capabilities, supported platforms, available middleware, hiring pool, and long-term maintenance cost. Unlike web framework selection where migration is painful but possible, switching game engines mid-project is effectively starting over. This decision must be made deliberately, with explicit tradeoff acknowledgment, and documented as an ADR.

package/content/knowledge/game/game-ideation.md

@@ -2,6 +2,10 @@
 name: game-ideation
 description: Game-specific ideation techniques for spark — core loop, player fantasy, retention, session design, monetization
 topics: [game-dev, ideation, core-loop, player-fantasy, retention, monetization, session-design]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game ideation applies game-specific lenses — core loop, player fantasy, retention mechanics, session design, and monetization — to the spark tool's ideation flow. It supplements the general ideation-craft entry when a user is exploring a game idea.

package/content/knowledge/game/game-input-systems.md

@@ -2,6 +2,10 @@
 name: game-input-systems
 description: Input abstraction patterns, action mapping, dead zones, aim assist, haptic feedback, cross-play fairness, and accessibility
 topics: [game-dev, input, controls, rebinding, haptics, accessibility]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 The input system is the player's sole interface with the game world. Every millisecond of input latency, every unintuitive binding, and every inaccessible control scheme directly erodes the player's experience. A well-designed input system abstracts hardware differences behind a unified action layer, supports rebinding without code changes, handles device hotswap gracefully, and provides accessibility options that let every player engage with the game. Input systems are deceptively complex — the gap between "reading a button press" and "shipping a polished, accessible, cross-platform input system" is enormous.

package/content/knowledge/game/game-level-content-design.md

@@ -2,6 +2,10 @@
 name: game-level-content-design
 description: Level metrics, greyboxing standards, flow and pacing, streaming strategies, encounter design, procedural generation, and difficulty curves
 topics: [game-dev, level-design, world-design, procedural, streaming]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Level design is the discipline of building the spaces that players inhabit and the experiences they have within those spaces. It bridges game design, environment art, and engineering — a level designer must understand player movement metrics (how high can they jump, how fast do they run, how wide is their collision capsule), pacing principles (tension-release cycles, difficulty ramps), and technical constraints (streaming budgets, draw call limits, memory footprints). Good level design is invisible: the player feels guided without feeling railroaded, challenged without feeling frustrated, and rewarded without feeling manipulated.

package/content/knowledge/game/game-liveops-analytics.md

@@ -2,6 +2,10 @@
 name: game-liveops-analytics
 description: Data taxonomy, telemetry pipelines, A/B testing, content cadence, seasonal events, post-launch support, and KPI-driven decision making
 topics: [game-dev, analytics, liveops, telemetry, kpi, ab-testing]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Live operations (LiveOps) and analytics transform a game from a one-time product into a continuously evolving service. The core discipline is building feedback loops: instrument player behavior, analyze the data, form hypotheses, ship changes, measure results. Without robust telemetry and a clear KPI hierarchy, LiveOps teams operate blind — making content decisions based on gut feel, missing retention cliffs, and shipping events that move no needle. Games that invest in data infrastructure from early production gain a compounding advantage: every content update is informed by the last, every A/B test sharpens understanding of the player base, and every seasonal event builds on measured engagement patterns.

package/content/knowledge/game/game-localization.md

@@ -2,6 +2,10 @@
 name: game-localization
 description: String management, font atlas pipeline, text expansion, subtitle standards, VO localization, culturalization, and LQA methodology
 topics: [game-dev, localization, l10n, lqa, fonts, rtl]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game localization is not translation — it is the engineering and cultural adaptation required to make a game feel native in every target market. A translated string that does not fit the UI, a font that cannot render Chinese characters, a gesture that is offensive in Brazil, or a subtitle that flashes too fast for reading speed norms — each of these failures breaks immersion and signals to the player that they are an afterthought. Localization touches every layer of the stack: string management, rendering, audio, UI layout, cultural review, and QA. The cost of retrofitting localization into a game that was not designed for it is 3-5x higher than building it in from the start.

package/content/knowledge/game/game-milestone-definitions.md

@@ -2,6 +2,10 @@
 name: game-milestone-definitions
 description: Standard game development milestones from concept through live ops, gate criteria, and task-wave mapping
 topics: [game-dev, milestones, production, vertical-slice, alpha, beta]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game development milestones are the checkpoints that determine whether a project is on track, at risk, or should be cancelled. Unlike software sprints that deliver incremental value, game milestones represent qualitative gates — each one answers a fundamentally different question about the project. Missing a milestone gate criteria is a signal that should trigger re-evaluation, not just a schedule adjustment. The discipline to enforce gate criteria is what separates shipped games from cancelled ones.

package/content/knowledge/game/game-modding-ugc.md

@@ -2,6 +2,10 @@
 name: game-modding-ugc
 description: Mod API design, packaging formats, sandboxing, versioning, content moderation, distribution platforms, and file-based loading
 topics: [game-dev, modding, ugc, sandbox, steam-workshop, mod-api]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Modding and user-generated content (UGC) transform a game from a finished product into a platform. The most enduring games in history — Minecraft, Skyrim, Counter-Strike (itself a mod), DOTA (a Warcraft III mod), Garry's Mod — owe their longevity to modding communities that produce content at a scale no studio can match. But modding support is not free: it requires deliberate API design, security sandboxing, compatibility management across game updates, content moderation, and distribution infrastructure. A poorly designed mod system creates more problems than it solves — crashes blamed on the base game, security exploits, copyright-infringing content, and player fragmentation. The goal is to expose enough of the game's systems to enable creativity while maintaining stability, security, and a coherent player experience.

package/content/knowledge/game/game-narrative-design.md

@@ -2,6 +2,10 @@
 name: game-narrative-design
 description: Dialogue tree patterns, branching narrative frameworks, lore bible structure, environmental storytelling, and localization hooks
 topics: [game-dev, narrative, dialogue, branching, lore, worldbuilding]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game narrative design is the discipline of telling stories through interactive systems. Unlike film or literature, game narrative must account for player agency — the story adapts to player choices, pacing varies with player skill, and narrative is delivered through gameplay mechanics as much as through dialogue. The narrative designer's job is to create systems that deliver story, not just write scripts. This requires understanding dialogue tree architectures, branching frameworks, environmental storytelling techniques, and the technical infrastructure that supports narrative at scale.

package/content/knowledge/game/game-networking.md

@@ -2,6 +2,10 @@
 name: game-networking
 description: Client-server and P2P architectures, tick rates, client prediction, server reconciliation, lag compensation, and anti-cheat
 topics: [game-dev, networking, netcode, multiplayer, prediction, reconciliation]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game networking is fundamentally different from web or API networking because it must maintain a shared simulation across multiple machines with divergent latencies, all while feeling instantaneous to each player. The core tension is between responsiveness (the player's actions feel immediate) and authority (the server is the source of truth). Every multiplayer game exists on a spectrum between these two poles, and the netcode architecture determines where on that spectrum the game sits. Getting this wrong produces unplayable results — rubber-banding, ghost hits, desync, and exploitable clients.

package/content/knowledge/game/game-performance-budgeting.md

@@ -2,6 +2,10 @@
 name: game-performance-budgeting
 description: Frame budget allocation, memory budgets per platform, GPU/draw call limits, loading targets, thermal constraints, and profiling tools
 topics: [game-dev, performance, frame-budget, memory, gpu, optimization]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Performance budgeting is the discipline of allocating fixed time, memory, and GPU resource envelopes to each game subsystem and enforcing those limits throughout development. Unlike web performance where a slow page is merely annoying, a missed frame budget in a game causes visible hitches, input lag, and motion sickness in VR. Budgets must be established at project start, measured continuously with profiling tools, and treated as hard constraints — not aspirational targets.

package/content/knowledge/game/game-platform-certification.md

@@ -2,6 +2,12 @@
 name: game-platform-certification
 description: Sony TRC, Microsoft XR, Nintendo Lotcheck, mobile store guidelines, Steam Deck compatibility review, and common failure points
 topics: [game-dev, certification, trc, tcr, xr, lotcheck, app-store]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://developer.apple.com/app-store/review/guidelines/
+  - url: https://developer.android.com/distribute/play-policies
 ---
 
 Platform certification is the gatekeeping process each platform holder uses to ensure games meet minimum technical and policy standards before release. Every platform has its own requirements document, submission process, and failure criteria. Failing certification delays launch by days to weeks per resubmission, and each failure costs time, money, and morale. Understanding common failure points and building pre-check routines into your development process is far cheaper than discovering issues during formal submission.

package/content/knowledge/game/game-project-structure.md

@@ -2,6 +2,10 @@
 name: game-project-structure
 description: Engine-specific directory conventions for Unity, Unreal, and Godot with asset and code organization strategies
 topics: [game-dev, project-structure, unity, unreal, godot, organization]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game projects have fundamentally different structure requirements than web or business applications because they manage two distinct artifact types: code and content assets. Code follows software engineering conventions (modules, namespaces, tests). Content assets follow production pipeline conventions (source art, exported formats, level data, audio banks). The directory structure must serve both engineers and content creators, and it must scale from prototype to shipped product without requiring a mid-project reorganization.

package/content/knowledge/game/game-save-systems.md

@@ -2,6 +2,10 @@
 name: game-save-systems
 description: Save formats, versioning and migration, cloud save integration, auto-save design, corruption detection, and platform requirements
 topics: [game-dev, save, persistence, cloud-save, corruption, migration]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Save systems are the custodians of player investment. A corrupted save file can destroy hundreds of hours of progress and generate visceral negative reviews. A missing cloud sync can strand progress on the wrong device. A format that cannot be versioned locks the game out of future content updates. Despite this criticality, save systems are frequently under-engineered — treated as simple serialization when they are actually distributed state management with backward compatibility, corruption recovery, and platform-specific compliance requirements. Build the save system early, test it adversarially, and treat save data loss as a severity-one bug.

package/content/knowledge/game/game-testing-strategy.md

@@ -2,6 +2,10 @@
 name: game-testing-strategy
 description: Simulation logic testing, visual and performance regression, soak testing, balance validation, playtest protocols, and CI integration
 topics: [game-dev, testing, playtesting, soak, balance, visual-regression]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game testing spans a far wider range than typical software testing. Beyond unit and integration tests for code, games require visual regression testing (did the shader change break the look of every material?), performance regression testing (did the new particle system push frame time over budget?), soak testing (does the game crash after 48 hours of continuous play?), balance validation (is the new weapon overpowered?), and structured playtesting with real humans. Each testing layer catches a different class of defect, and skipping any layer means shipping that class of bug to players.

package/content/knowledge/game/game-ui-patterns.md

@@ -2,6 +2,10 @@
 name: game-ui-patterns
 description: HUD patterns, menu hierarchy, controller-first navigation, settings screens, split-screen adaptation, and in-game commerce flows
 topics: [game-dev, ui, hud, menus, controller-navigation, settings]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game UI serves two fundamentally different purposes simultaneously: it must convey critical gameplay information without obscuring the game world (the HUD), and it must provide navigable menu systems that work equally well with mouse, gamepad, touch, and keyboard (the menu layer). Unlike web or mobile app UI where mouse/touch is assumed, game UI must be designed controller-first for any title shipping on console — focus management, D-pad navigation flow, and button prompt adaptation are not optional features bolted on later but architectural decisions made at the start of UI development.

package/content/knowledge/game/game-vr-ar-design.md

@@ -2,6 +2,12 @@
 name: game-vr-ar-design
 description: VR comfort and locomotion, stereo rendering budgets, spatial UI, hand tracking, gaze interaction, motion sickness, and certification
 topics: [game-dev, vr, ar, comfort, locomotion, spatial-ui]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://developer.apple.com/visionos/
+  - url: https://developer.android.com/develop/xr
 ---
 
 VR and AR development is fundamentally constrained by human physiology in ways that flat-screen development is not. Every design decision — camera movement, UI placement, rendering performance, input method — must account for the vestibular system, visual comfort, and spatial cognition of the player. A frame drop that is a minor annoyance on a monitor becomes nausea-inducing in a headset. A UI panel that works at arm's length on a screen becomes unreadable at 0.5 meters or causes eye strain at 0.3 meters. Motion that the player did not initiate with their own body creates a sensory conflict that the brain interprets as poisoning. VR/AR design is not flat-screen design with head tracking bolted on — it requires rethinking interaction, performance, and comfort from first principles.

package/content/knowledge/library/library-api-design.md

@@ -2,6 +2,10 @@
 name: library-api-design
 description: Public surface design, method signatures, error contracts, and extension points for published library APIs
 topics: [library, api-design, public-surface, method-signatures, error-contracts, extension-points]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Library API design is the highest-leverage activity in library development. A well-designed API makes correct usage easy and incorrect usage hard, survives multiple major versions without fundamental restructuring, and communicates intent through its shape alone. Poor API design cannot be fixed without breaking changes — every naming mistake, parameter order error, and missing overload becomes permanent once consumers adopt it. Design APIs from the consumer's perspective first, implementation second.

package/content/knowledge/library/library-architecture.md

@@ -2,6 +2,10 @@
 name: library-architecture
 description: Module design, dependency minimization, tree-shaking enablement, and plugin patterns for published libraries
 topics: [library, architecture, modules, tree-shaking, plugins, dependencies, design]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Library architecture is constrained by two forces that do not apply to applications: the consumer's bundle size budget and the consumer's dependency graph. Every architectural decision must account for what the library adds to consumers who import it — not just the feature complexity it solves. A well-architected library is modular by default, has minimal or zero runtime dependencies, enables tree-shaking so consumers pay only for what they use, and provides extension points that don't require forking the library.

package/content/knowledge/library/library-bundling.md

@@ -2,6 +2,10 @@
 name: library-bundling
 description: ESM/CJS dual publishing, package.json exports map, bundler configuration, and tree-shaking verification for libraries
 topics: [library, bundling, esm, cjs, dual-publishing, exports-map, tree-shaking, tsup, rollup]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Library bundling solves the problem of serving multiple module systems from one codebase. The JavaScript ecosystem is mid-transition from CommonJS to ES modules, and libraries must serve both until the transition completes. Getting bundling wrong produces libraries that fail to import in certain environments, cause dual-package hazards (two instances of the same library loaded simultaneously), or defeat tree-shaking and inflate consumer bundle sizes.

package/content/knowledge/library/library-conventions.md

@@ -2,6 +2,11 @@
 name: library-conventions
 description: Public API naming, deprecation patterns, changelog conventions, and export patterns for published libraries
 topics: [library, conventions, naming, deprecation, changelog, exports, api-design]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://www.conventionalcommits.org/en/v1.0.0/
 ---
 
 Library conventions are the agreements that make a library predictable, navigable, and trustworthy across versions. They cover how public APIs are named, how deprecated APIs are marked and eventually removed, how changes are communicated through changelogs, and how exports are structured. Inconsistent conventions are a tax on every consumer — they create confusion about what is stable, what is safe to use, and what changed between versions.

package/content/knowledge/library/library-dev-environment.md

@@ -2,6 +2,10 @@
 name: library-dev-environment
 description: Monorepo setup, npm link workflow, build watch mode, and local consumer testing for library development
 topics: [library, dev-environment, monorepo, npm-link, build-watch, local-testing]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Library development environment setup is distinct from application development: you are building code that will be consumed by other projects, which means your dev workflow must include a way to test the library as a consumer would — before publishing to npm. The feedback loop between changing library source and seeing the effect in a consumer application is the central challenge. Get this wrong, and you spend hours debugging issues that only surface after publish.

package/content/knowledge/library/library-documentation.md

@@ -2,6 +2,10 @@
 name: library-documentation
 description: TypeDoc/JSDoc setup, README structure, example code, migration guides, and API reference for published libraries
 topics: [library, documentation, typedoc, jsdoc, readme, examples, migration-guides, api-reference]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Library documentation is the primary onboarding surface for new consumers and the support surface for existing ones. Poor documentation causes consumers to misuse the API, open avoidable issues, and ultimately abandon the library for better-documented alternatives. Good documentation reduces support burden, increases adoption, and communicates the library's quality and professionalism. Documentation must be treated as a first-class deliverable, not an afterthought after code is complete.

package/content/knowledge/library/library-project-structure.md

@@ -2,6 +2,10 @@
 name: library-project-structure
 description: Directory layout, package.json exports map, tsconfig for declarations, and examples/ structure for published libraries
 topics: [library, project-structure, package-json, tsconfig, exports, declarations]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Library project structure must serve two audiences simultaneously: contributors who need to navigate and modify the source, and consumers who install the package and expect predictable module resolution. The structure of the source directory, the `dist/` output, the `package.json` exports map, and the TypeScript configuration all interlock. Getting any one of them wrong produces libraries that fail to tree-shake, ship broken types, or cause dual-package hazards.

package/content/knowledge/library/library-requirements.md

@@ -2,6 +2,10 @@
 name: library-requirements
 description: API contract stability, semver commitments, consumer compatibility, and breaking change policy for published libraries
 topics: [library, requirements, semver, api-contract, breaking-changes, compatibility]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Library requirements differ fundamentally from application requirements: every public API decision becomes a contract with downstream consumers who cannot easily update. Stability, predictability, and clear communication of change are the highest-priority concerns. A library that breaks its consumers silently, or without adequate notice, loses trust permanently.

package/content/knowledge/library/library-security.md

@@ -2,6 +2,10 @@
 name: library-security
 description: Supply chain security, dependency auditing, npm provenance, SBOM, and security policy for published libraries
 topics: [library, security, supply-chain, npm-provenance, sbom, dependency-auditing, cve]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Library security is supply chain security. When a library is published to npm and installed by thousands of projects, a single compromised release or a malicious dependency can propagate vulnerabilities to all consumers simultaneously. The 2021 `ua-parser-js` incident and the 2022 `node-ipc` sabotage demonstrated that even widely-used libraries with established maintainers can be compromised. Library authors bear a responsibility to their consumers that application developers do not — a security failure in a library is a security failure for every project that depends on it.

package/content/knowledge/library/library-testing.md

@@ -2,6 +2,10 @@
 name: library-testing
 description: Unit tests, consumer integration tests, example app tests, snapshot testing, and type testing for published libraries
 topics: [library, testing, unit-tests, integration-tests, type-testing, tsd, snapshot-testing, consumer-testing]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Library testing has a different threat model than application testing. You are not just testing that your code works internally — you are testing that the public API works correctly from a consumer's perspective, across different environments and module systems, and that type definitions accurately reflect runtime behavior. A library with excellent unit tests but untested consumer integration can still fail spectacularly when installed in a real project. Every public API export needs test coverage that exercises it as a consumer would.

package/content/knowledge/library/library-type-definitions.md

@@ -2,6 +2,10 @@
 name: library-type-definitions
 description: Declaration files (.d.ts), type testing with tsd/expect-type, conditional types, and API surface documentation via types
 topics: [library, typescript, type-definitions, declarations, tsd, expect-type, conditional-types, dts]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Type definitions are a first-class deliverable for TypeScript libraries. They are part of the public API contract, not an afterthought. Declaration files (`.d.ts`) must be accurate, complete, and expressive — they determine whether consumers can use the library with type safety, whether IDEs provide useful completions, and whether type errors are caught at compile time rather than runtime. Inaccurate types are worse than no types because they create false confidence.

package/content/knowledge/library/library-versioning.md

@@ -2,6 +2,11 @@
 name: library-versioning
 description: Semver discipline, breaking change detection, release automation, and changelog management for published libraries
 topics: [library, versioning, semver, breaking-changes, release-automation, changelog, changesets]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://www.conventionalcommits.org/en/v1.0.0/
 ---
 
 Library versioning is a communication protocol with consumers. Semver (Semantic Versioning) is not merely a numbering scheme — it is a contract about backward compatibility. Breaking that contract without a major version bump is one of the most damaging things a library can do. Consumers set version ranges expecting that minor updates are safe to take automatically. Violating that expectation causes production incidents for real applications. Versioning discipline must be enforced by tooling, not willpower.

package/content/knowledge/ml/ml-architecture.md

@@ -2,6 +2,10 @@
 name: ml-architecture
 description: Training/serving architecture split, feature stores, model registry, online vs offline inference patterns, and ML system design decisions
 topics: [ml, architecture, feature-store, model-registry, inference, serving, training]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 ML systems have a fundamental architectural split that traditional software does not: the training system and the serving system are different codebases running on different infrastructure, yet they must agree on the exact same data transformations. This training-serving skew is the most common source of silent production bugs in ML. Designing the architecture to prevent skew — through shared feature stores, shared preprocessing libraries, and strict interface contracts — is the most important ML architecture decision.

package/content/knowledge/ml/ml-conventions.md

@@ -2,6 +2,10 @@
 name: ml-conventions
 description: Experiment naming, model versioning, reproducibility via random seeds, config-as-code patterns, and team conventions for ML projects
 topics: [ml, conventions, reproducibility, versioning, config, experiments]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 ML projects without conventions degenerate into chaos within weeks: unnamed experiments with lost hyperparameters, models named `model_v2_final_FINAL.pkl`, and results that cannot be reproduced. Unlike software engineering where the compiler enforces structure, ML workflows are loose scripts and notebooks that require disciplined conventions to remain comprehensible. Establish these conventions at project start and encode them in tooling so they are followed by default, not willpower.

package/content/knowledge/ml/ml-dev-environment.md

@@ -2,6 +2,10 @@
 name: ml-dev-environment
 description: Conda/Poetry environment setup, Jupyter integration, GPU detection and configuration, and Docker for reproducible ML development
 topics: [ml, dev-environment, conda, poetry, jupyter, gpu, docker, reproducibility]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 ML development environments have more complexity than typical software projects: GPU drivers, CUDA toolkits, Python packages with native extensions, and Jupyter notebook infrastructure all need to align. A broken environment costs hours and blocks the whole team. Invest in environment standardisation upfront — the payoff is that every team member can reproduce results and that CI pipelines match local runs.

package/content/knowledge/ml/ml-experiment-tracking.md

@@ -2,6 +2,12 @@
 name: ml-experiment-tracking
 description: MLflow and Weights & Biases integration, artifact storage, experiment run comparison, and hyperparameter sweep management
 topics: [ml, experiment-tracking, mlflow, wandb, artifacts, sweeps, reproducibility]
+volatility: fast-moving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://mlflow.org/docs/latest/index.html
+  - url: https://docs.wandb.ai/
 ---
 
 Without experiment tracking, ML development is archaeology: "which config produced that result?" is answered by digging through notebook history, chat logs, and failing memory. Experiment tracking tools are version control for training runs — every metric, every hyperparameter, every artifact, linked to the code that produced it. The discipline of logging everything during training pays dividends when a stakeholder asks "how does this model compare to what we had six months ago?"

package/content/knowledge/ml/ml-model-evaluation.md

@@ -2,6 +2,10 @@
 name: ml-model-evaluation
 description: Train/val/test splits, cross-validation, metrics by task type, holdout sets, and slice analysis for thorough model evaluation
 topics: [ml, evaluation, train-test-split, cross-validation, metrics, holdout, slice-analysis]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Model evaluation is the difference between knowing whether your model works and believing it works. Most ML evaluation bugs are forms of data leakage: the model has seen information during training that it would not have at inference time, making offline metrics look better than production performance. Rigorous evaluation requires careful data splitting, leak-free preprocessing, appropriate metrics for the task, and systematic analysis of where the model fails.

package/content/knowledge/ml/ml-observability.md

@@ -2,6 +2,11 @@
 name: ml-observability
 description: Model monitoring for drift and decay, prediction logging, explainability tools, and alerting on accuracy drops in production ML systems
 topics: [ml, observability, monitoring, drift, model-decay, explainability, alerting, prediction-logging]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://opentelemetry.io/docs/
 ---
 
 A model deployed to production without monitoring is a ticking clock. Models decay silently: the world changes, input distributions shift, and accuracy degrades while dashboards show green. Unlike software bugs that throw exceptions, model degradation has no stack trace — predictions simply become less useful. ML observability is the discipline of detecting these degradations before users notice them, through systematic monitoring of model inputs, outputs, and outcomes.

package/content/knowledge/ml/ml-project-structure.md

@@ -2,6 +2,10 @@
 name: ml-project-structure
 description: Standard ML project directory layout covering src/data, src/models, src/training, src/serving, notebooks, configs, and model artifact storage
 topics: [ml, project-structure, layout, organization, artifacts, notebooks]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 ML projects accumulate files faster than almost any other software domain: datasets, model checkpoints, experiment configs, notebooks, evaluation reports, and serving code. Without a deliberate directory structure, projects become disorganised within weeks and impossible to onboard new team members onto. A well-structured ML project separates concerns clearly: source code from notebooks, training from serving, configs from code, and tracked artifacts from ephemeral outputs.

package/content/knowledge/ml/ml-requirements.md

@@ -2,6 +2,10 @@
 name: ml-requirements
 description: Model performance metrics (accuracy, latency, throughput), business KPIs, fairness/bias requirements, and SLA definitions for ML systems
 topics: [ml, requirements, metrics, fairness, bias, sla, kpi]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 ML requirements differ from traditional software requirements because correctness is probabilistic, not absolute. Before writing a single line of training code, define the target metrics, their measurement methodology, and the business KPIs they serve. Ambiguous requirements — "make the model accurate" — are the root cause of most ML project failures. A requirements document for an ML system must specify numeric thresholds, measurement conditions, and what constitutes an acceptable production deployment.

package/content/knowledge/ml/ml-security.md

@@ -2,6 +2,11 @@
 name: ml-security
 description: ML-specific threats including adversarial attacks and data poisoning, PII handling in training data, model IP protection, and access control for ML systems
 topics: [ml, security, adversarial-attacks, data-poisoning, pii, model-ip, access-control]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://owasp.org/www-project-machine-learning-security-top-10/
 ---
 
 ML systems introduce a new class of security threats that traditional application security does not address. A model trained on poisoned data may behave normally on most inputs but trigger on specific attacker-controlled patterns. A model served via API leaks information about its training data to membership inference attacks. These are not theoretical — they are exploited in production systems. ML security requires defence-in-depth across the data pipeline, training process, and serving infrastructure.

package/content/knowledge/ml/ml-serving-patterns.md

@@ -2,6 +2,10 @@
 name: ml-serving-patterns
 description: Model serving with TorchServe, Triton, and BentoML; batch vs realtime inference patterns; A/B testing and canary deployment strategies
 topics: [ml, serving, torchserve, triton, bentoml, inference, ab-testing, canary, deployment]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Model serving is where ML meets production software engineering. A model that performs well in a notebook is worthless if it cannot serve predictions reliably at scale. Serving patterns address the gap between "it works on my machine" and "it handles 10,000 requests per second with P99 < 100ms and zero data races." The serving layer must be treated with the same engineering rigour as any production microservice.

package/content/knowledge/ml/ml-testing.md

@@ -2,6 +2,10 @@
 name: ml-testing
 description: Unit tests for data transforms, tolerance-based model tests, pipeline integration tests, and regression tests for ML systems
 topics: [ml, testing, unit-tests, model-tests, pipeline-tests, regression-tests, tdd]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 ML code is tested less rigorously than traditional software because "the model is probabilistic" feels like an excuse for skipping tests. It is not. The vast majority of ML code — data transforms, preprocessing, feature engineering, postprocessing, and serving logic — is deterministic and must be unit tested. The probabilistic parts — model weights and accuracy — require tolerance-based tests and regression baselines. Untested ML pipelines fail silently in ways that are expensive to diagnose in production.

package/content/knowledge/ml/ml-training-patterns.md

@@ -2,6 +2,10 @@
 name: ml-training-patterns
 description: Data loaders, training loops, distributed training with DDP and FSDP, checkpointing strategies, and hyperparameter tuning patterns
 topics: [ml, training, data-loaders, distributed-training, ddp, fsdp, checkpointing, hyperparameter-tuning]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 The training loop is the heart of every ML project, but it is also where most bugs hide: data leaking between splits, gradients not zeroed, mixed precision overflows, checkpoints saved incorrectly, and distributed training hanging on a single slow worker. These are not exotic edge cases — they are the standard bugs that every ML engineer encounters. A well-structured training pipeline prevents them through clear separation of concerns and defensive coding.

package/content/knowledge/mobile-app/mobile-app-architecture.md

@@ -2,6 +2,12 @@
 name: mobile-app-architecture
 description: MVVM/MVI/TCA patterns, navigation architecture, dependency injection, and state management for iOS and Android mobile apps
 topics: [mobile-app, architecture, mvvm, mvi, tca, navigation, dependency-injection, state-management]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://developer.apple.com/documentation/swiftui
+  - url: https://developer.android.com/topic/architecture
 ---
 
 Mobile app architecture determines testability, scalability, and developer velocity. The wrong architecture is expensive to reverse — a monolithic ViewController or God Activity becomes unmaintainable at scale. Both iOS and Android ecosystems have converged on unidirectional data flow patterns: TCA and MVVM+Combine/async for iOS, MVI and MVVM+Flow for Android. Choose the pattern that matches your team's size and complexity requirements, not the most sophisticated available option.

package/content/knowledge/mobile-app/mobile-app-conventions.md

@@ -2,6 +2,12 @@
 name: mobile-app-conventions
 description: Platform naming conventions, accessibility patterns, navigation patterns, and code style for iOS and Android mobile apps
 topics: [mobile-app, conventions, swift, kotlin, naming, accessibility, navigation]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://developer.apple.com/design/human-interface-guidelines
+  - url: https://developer.android.com/design
 ---
 
 Mobile platform conventions exist for consistency across the ecosystem, toolchain compatibility, and team readability. iOS and Android have distinct naming conventions, navigation paradigms, and accessibility implementation patterns. Mixing conventions or importing web/backend naming styles into mobile code creates cognitive friction and breaks tooling assumptions (SwiftUI previews, Android Studio refactoring, lint rules).

package/content/knowledge/mobile-app/mobile-app-deployment.md

@@ -2,6 +2,12 @@
 name: mobile-app-deployment
 description: App store submission, code signing, provisioning profiles, CI/CD with Fastlane, and release management for iOS and Android
 topics: [mobile-app, deployment, app-store, google-play, code-signing, fastlane, ci-cd, release-management]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://developer.apple.com/app-store/review/guidelines/
+  - url: https://developer.android.com/studio/publish
 ---
 
 Mobile app deployment is significantly more complex than web deployment: code signing creates a cryptographic chain of trust, app store review is a human process with 24–48 hour latency, and binary deployment means bugs cannot be hot-patched without a full submission cycle. Automate as much of this as possible with Fastlane — manual signing and upload processes are error-prone and do not scale to frequent releases.