@kb-labs/mind-contracts 2.93.0 → 2.96.0

package/README.md

@@ -1,174 +1,23 @@
 # @kb-labs/mind-contracts
 
-Public contracts for the KB Labs Mind plugin. Declares artifacts, commands, workflows, and API guarantees for consumers.
+Wire contracts for the KB Labs **Mind** (RAG) plugin — the thin boundary shared
+between the CLI, REST, and any other consumer.
 
-## Vision & Purpose
+Contains only Zod schemas, CLI flag definitions, route constants, and per-index
+config resolution. Imports nothing but `@kb-labs/sdk` and `zod` — no platform
+internals, no runtime logic.
 
-**@kb-labs/mind-contracts** provides public contracts for KB Labs Mind. It describes the guarantees that other products (CLI, Studio, REST gateway, Workflow Engine) can rely on without depending on Mind runtime code.
+## Exports
 
-### Core Goals
+- **Schemas** — `index`, `search`, `query`/agent, `explore`, `sync`, `status`
+  request/response shapes (`*RequestSchema` / `*ResponseSchema`).
+- **Flags** — `indexFlags`, `searchFlags`, `askFlags`, `exploreFlags`,
+  `syncPathsFlags`, `reindexFlags`, `statusFlags`.
+- **Config** — `MindConfigSchema`, `effectiveIndexConfig(config, indexId)`
+  (global config + named-index overrides).
+- **Routes** — `MIND_BASE_PATH`, `MIND_ROUTES`, `MIND_FULL_ROUTES`.
 
-- **Contract Definition**: Define public contracts for Mind
-- **Schema Validation**: Zod schemas for validation
-- **Type Safety**: TypeScript types derived from schemas
-- **Versioning**: SemVer-based contract versioning
+## Layer
 
-## Package Status
-
-- **Version**: 0.1.0
-- **Stage**: Stable
-- **Status**: Production Ready ✅
-
-## Architecture
-
-### High-Level Overview
-
-```
-Mind Contracts
-    │
-    ├──► Contract Manifest
-    ├──► Zod Schemas
-    ├──► TypeScript Types
-    └──► Helper Parsers
-```
-
-### Key Components
-
-1. **Contract Manifest** (`contract.ts`): Plugin contracts manifest
-2. **Schemas** (`schema/`): Zod validation schemas
-3. **Types** (`types.ts`): TypeScript type definitions
-4. **Parsers** (`schema.ts`): Helper parsers
-
-## ✨ Features
-
-- **Contract Manifest**: Typed declaration of Mind artifacts, commands, workflows, and REST routes
-- **Zod Schemas**: Validation schemas for CLI flag definitions, query DTOs, REST responses, Studio widgets
-- **TypeScript Types**: Type definitions for command inputs/outputs
-- **Helper Parsers**: `parsePluginContracts` for runtime validation
-
-## 📦 API Reference
-
-### Main Exports
-
-#### Contract Manifest
-
-- `pluginContractsManifest`: Typed declaration of Mind artifacts, commands, workflows, and REST routes
-- `contractsVersion`: SemVer version for contract coordination
-- `contractsSchemaId`: Schema ID for contract validation
-
-#### Schemas
-
-- `parsePluginContracts`: Parse plugin contracts
-- `pluginContractsSchema`: Plugin contracts schema
-
-#### Types
-
-- `PluginContracts`: Plugin contracts type
-- `ArtifactDecl`: Artifact declaration type
-- `CommandDecl`: Command declaration type
-
-## 🔧 Configuration
-
-### Configuration Options
-
-No configuration needed - pure contract definitions.
-
-## 🔗 Dependencies
-
-### Runtime Dependencies
-
-- `zod` (`^3.23.8`): Schema validation
-
-### Development Dependencies
-
-- `@kb-labs/devkit` (`link:../../../kb-labs-devkit`): DevKit presets
-- `@types/node` (`^24.7.0`): Node.js types
-- `semver` (`^7.6.3`): SemVer parsing
-- `tsup` (`^8.5.0`): TypeScript bundler
-- `typescript` (`^5.6.3`): TypeScript compiler
-- `vitest` (`^3.2.4`): Test runner
-
-## 🧪 Testing
-
-### Test Structure
-
-```
-tests/
-└── contracts.manifest.test.ts
-```
-
-### Test Coverage
-
-- **Current Coverage**: ~70%
-- **Target Coverage**: 90%
-
-## 📈 Performance
-
-### Performance Characteristics
-
-- **Time Complexity**: O(1) for type operations, O(n) for schema validation
-- **Space Complexity**: O(1)
-- **Bottlenecks**: Schema validation for large payloads
-
-## 🔒 Security
-
-### Security Considerations
-
-- **Schema Validation**: Input validation via Zod schemas
-- **Type Safety**: TypeScript type safety
-
-### Known Vulnerabilities
-
-- None
-
-## 🐛 Known Issues & Limitations
-
-### Known Issues
-
-- None currently
-
-### Limitations
-
-- **Schema Validation**: Basic validation only
-
-### Future Improvements
-
-- **Enhanced Validation**: More validation rules
-
-## 🔄 Migration & Breaking Changes
-
-### Versioning Rules
-
-- **MAJOR** — breaking changes (removed fields, renamed IDs, incompatible schema updates)
-- **MINOR** — backwards-compatible additions (new flags, artifacts, optional fields)
-- **PATCH** — metadata/documentation tweaks that do not alter payload structure
-
-### Breaking Changes in Future Versions
-
-- None planned
-
-## 📚 Examples
-
-### Example 1: Use Contract Manifest
-
-```typescript
-import { pluginContractsManifest } from '@kb-labs/mind-contracts';
-
-const queryArtifactId = pluginContractsManifest.artifacts['mind.query.json'].id;
-```
-
-### Example 2: Parse Plugin Contracts
-
-```typescript
-import { parsePluginContracts } from '@kb-labs/mind-contracts';
-
-const contracts = parsePluginContracts(rawManifest);
-```
-
-## 🤝 Contributing
-
-See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
-
-## 📄 License
-
-MIT © KB Labs
+Layer 1 (contracts). Depended on by `@kb-labs/mind-core` and
+`@kb-labs/mind-entry`; depends on nothing internal.