@zigrivers/scaffold 3.28.0 → 3.29.0

package/content/knowledge/execution/multi-agent-coordination.md

@@ -2,11 +2,22 @@
 name: multi-agent-coordination
 description: Upstream Beads primitives for coordinating parallel agents — bd merge-slot for serialized merge resolution and bd gate for async coordination
 topics: [beads, multi-agent, worktrees, merge-conflicts, coordination, parallel-execution]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://github.com/steveyegge/beads
 ---
 
 # Multi-Agent Coordination (Beads Primitives)
 
-When multiple agents work in parallel worktrees and converge on `main`, two upstream Beads primitives prevent the most common coordination failures. Both are optional — scaffold's multi-agent flows work without them — but they meaningfully reduce coordination cost in active parallel workloads.
+## Summary
+
+When multiple agents work in parallel worktrees and converge on `main`, two upstream Beads primitives prevent the most common coordination failures: `bd merge-slot` serializes the rebase-and-push race so two agents finishing at once don't clobber each other, and `bd gate` lets a blocked task wait on an arbitrary asynchronous event (CI green, peer review, external approval). Both are optional — scaffold's multi-agent flows work without them — but they meaningfully reduce coordination cost in active parallel workloads.
+
+## Deep Guidance
+
+The two primitives below are the load-bearing Deep Guidance for this entry. The per-command sections explain when to acquire/release each, the failure modes, and the asynchronous coordination patterns they support. Treat the rest of this document (from this heading to EOF) as the section the assembly engine injects.
 
 ## `bd merge-slot` — serialized merge resolution
 

package/content/knowledge/execution/task-claiming-strategy.md

@@ -2,6 +2,10 @@
 name: task-claiming-strategy
 description: Task selection and management patterns for AI agent execution
 topics: [tasks, execution, agents, planning]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Task Claiming Strategy

package/content/knowledge/execution/tdd-execution-loop.md

@@ -2,6 +2,11 @@
 name: tdd-execution-loop
 description: Red-green-refactor execution cycle for AI agents
 topics: [tdd, execution, testing, workflow]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/bliki/TestDrivenDevelopment.html
 ---
 
 # TDD Execution Loop

package/content/knowledge/execution/worktree-management.md

@@ -2,6 +2,11 @@
 name: worktree-management
 description: Git worktree patterns for parallel multi-agent execution
 topics: [git, worktrees, multi-agent, branching]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://git-scm.com/docs/git-worktree
 ---
 
 # Worktree Management

package/content/knowledge/finalization/apply-fixes-and-freeze.md

@@ -2,6 +2,10 @@
 name: apply-fixes-and-freeze
 description: Guidance on prioritizing validation fixes, applying them safely, and freezing documentation for implementation
 topics: [finalization, fixes, freeze, validation, documentation-quality]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Apply Fixes and Freeze

package/content/knowledge/finalization/developer-onboarding.md

@@ -2,6 +2,10 @@
 name: developer-onboarding
 description: What an effective onboarding guide covers — repo setup, architecture overview, key patterns
 topics: [onboarding, documentation, getting-started, developer-experience]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Developer Onboarding

package/content/knowledge/finalization/implementation-playbook.md

@@ -2,6 +2,10 @@
 name: implementation-playbook
 description: Structuring work for AI agents — task execution, coding standards, git workflow, quality gates
 topics: [playbook, agents, implementation, coding-standards, git-workflow]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Implementation Playbook

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

@@ -2,6 +2,10 @@
 name: game-accessibility
 description: Xbox Accessibility Guidelines as best-practice guidance, game-specific a11y categories, CVAA scope, and low-cost high-impact features
 topics: [game-dev, accessibility, xag, cvaa, colorblind, remapping]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game accessibility is about removing barriers that prevent players with disabilities from experiencing your game. The Xbox Accessibility Guidelines (XAG) provide the most comprehensive industry framework — not as a legal compliance checklist, but as best-practice guidance that Microsoft explicitly positions as aspirational. Every feature you implement opens your game to more players, and many accessibility features (subtitles, remapping, difficulty options) benefit all players regardless of ability.

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

@@ -2,6 +2,10 @@
 name: game-ai-patterns
 description: Behavior trees, GOAP, utility AI, finite state machines, NavMesh pathfinding, perception systems, and companion AI
 topics: [game-dev, ai, behavior-trees, goap, pathfinding, npc]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game AI encompasses the systems that control non-player character behavior — from enemy combat tactics to companion pathfinding to ambient NPC routines. Unlike machine learning AI, game AI is deterministic and designed: every behavior is authored by a designer and executed by a runtime system. The goal is not intelligence but the appearance of intelligence — NPCs should behave in ways that feel believable, create interesting gameplay challenges, and respond to the player's actions in readable ways. The core trade-off in game AI is expressiveness vs. complexity: more sophisticated AI systems enable richer behavior but are harder to design, debug, and performance-tune.

package/content/knowledge/game/game-asset-pipeline.md

@@ -2,6 +2,10 @@
 name: game-asset-pipeline
 description: Asset naming taxonomies by engine, per-type specs (poly budgets, texture sizes, audio formats), DCC tool chains, Git LFS config, and file locking
 topics: [game-dev, assets, pipeline, naming, dcc, lfs]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 The asset pipeline is the full chain from an artist's DCC tool (Maya, Blender, Substance Painter, Houdini) through export, import, optimization, and packaging into the final game build. A well-structured pipeline enforces naming conventions, validates assets against per-type budgets on import, automates texture compression and LOD generation, and integrates with version control to prevent binary merge conflicts. Pipeline failures are insidious — a single 4K texture on a UI element or an uncompressed WAV in the audio bank can ship to players because nobody validated the asset against its budget.

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

@@ -2,6 +2,10 @@
 name: game-audio-design
 description: Wwise vs FMOD selection, bus hierarchy, spatial audio, adaptive music systems, VO pipeline, and platform loudness targets
 topics: [game-dev, audio, fmod, wwise, spatial-audio, adaptive-music]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game audio is not background decoration — it is a primary feedback channel that communicates game state, spatial awareness, emotional tone, and mechanical timing to the player. A gunshot tells the player where the enemy is, how far away they are, and what weapon they are using. Adaptive music builds tension before the player consciously recognizes danger. Missing or poorly mixed audio creates a hollow, unfinished experience that players feel even if they cannot articulate why. Audio architecture decisions (middleware, bus hierarchy, adaptive systems) must be made early because they affect content pipelines, memory budgets, and CPU budgets throughout production.

package/content/knowledge/game/game-binary-vcs-strategy.md

@@ -2,6 +2,11 @@
 name: game-binary-vcs-strategy
 description: Git LFS deep dive, Perforce and PlasticSCM comparison, large repo tuning, lock protocols, CI for binary assets, VCS selection guide
 topics: [game-dev, vcs, git-lfs, perforce, binary-assets]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://git-scm.com/docs/gitattributes
 ---
 
 Game development produces enormous volumes of binary assets — textures, meshes, audio, animations, and engine-specific formats — that fundamentally break assumptions baked into distributed version control systems like Git. A single Unreal project can exceed 100 GB of binary data that cannot be diffed, merged, or compressed efficiently. Choosing the right VCS strategy, configuring it correctly, and establishing team protocols around binary file workflows is a prerequisite for any multi-person game project. The wrong choice creates daily friction that compounds into weeks of lost productivity over a production cycle.

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.