@grainulation/silo 1.0.0 → 1.0.2

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Our standards
+
+We are committed to providing a welcoming and productive environment for everyone. We expect participants to:
+
+- Use welcoming and inclusive language
+- Respect differing viewpoints and experiences
+- Accept constructive criticism gracefully
+- Focus on what is best for the community and the project
+- Show empathy toward other participants
+
+Unacceptable behavior includes harassment, trolling, personal attacks, and publishing others' private information without permission.
+
+## Scope
+
+This code of conduct applies to all project spaces -- issues, pull requests, discussions, and any public channel where someone represents the project.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported to the project maintainers. All complaints will be reviewed and investigated, and will result in a response deemed necessary and appropriate.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing to Silo
+
+Thanks for considering contributing. Silo is the knowledge store for the grainulation ecosystem -- it indexes, searches, and manages claim packs across sprints.
+
+## Quick setup
+
+```bash
+git clone https://github.com/grainulation/silo.git
+cd silo
+node bin/silo.js --help
+```
+
+No `npm install` needed -- silo has zero dependencies.
+
+## How to contribute
+
+### Report a bug
+
+Open an issue with:
+
+- What you expected
+- What happened instead
+- Your Node version (`node --version`)
+- Steps to reproduce
+
+### Suggest a feature
+
+Open an issue describing the use case, not just the solution. "I need X because Y" is more useful than "add X."
+
+### Submit a PR
+
+1. Fork the repo
+2. Create a branch (`git checkout -b fix/description`)
+3. Make your changes
+4. Run the tests: `node test/basic.test.js`
+5. Commit with a clear message
+6. Open a PR
+
+### Add a knowledge pack
+
+Packs live in `packs/`. Each is a JSON file containing curated claims for a domain. To add one:
+
+1. Create `packs/your-domain.json`
+2. Follow the schema of existing packs (see `packs/architecture.json` for reference)
+3. Include claims with proper typing and evidence tiers
+4. Add a test case covering pack loading
+
+## Architecture
+
+```
+bin/silo.js               CLI entrypoint -- dispatches subcommands
+lib/index.js              Core library -- pack management and resolution
+lib/store.js              Persistent claim storage engine
+lib/search.js             Full-text and filtered claim search
+lib/analytics.js          Usage analytics and pack statistics
+lib/import-export.js      Bulk import/export of claim data
+lib/packs.js              Knowledge pack loading and validation
+lib/serve-mcp.js          MCP (Model Context Protocol) server
+lib/server.js             Local preview server (SSE, zero deps)
+lib/templates.js          Template rendering for HTML output
+packs/                    Built-in knowledge packs (JSON)
+public/                   Web UI -- search and browse interface
+site/                     Public website (silo.grainulation.com)
+test/                     Node built-in test runner tests
+```
+
+The key architectural principle: **silo is a content-addressable claim store.** Claims go in with typed metadata, and come out via search, pack membership, or direct ID lookup. The store is append-friendly and merge-safe.
+
+## Code style
+
+- Zero dependencies. If you need something, write it or use Node built-ins.
+- No transpilation. Ship what you write.
+- ESM imports (`import`/`export`). Node 18+ required.
+- Keep functions small. If a function needs a scroll, split it.
+- No emojis in code, CLI output, or pack data.
+
+## Testing
+
+```bash
+node test/basic.test.js
+```
+
+Tests use Node's built-in test runner. No test framework dependencies.
+
+## Commit messages
+
+Follow the existing pattern:
+
+```
+silo: <what changed>
+```
+
+Examples:
+
+```
+silo: add security knowledge pack
+silo: fix search ranking for multi-word queries
+silo: update import to handle duplicate claim IDs
+```
+
+## License
+
+MIT. See LICENSE for details.

package/README.md

@@ -1,40 +1,45 @@
-# @grainulation/silo
+<p align="center">
+  <img src="site/wordmark.svg" alt="Silo" width="400">
+</p>
 
-Reusable knowledge for research sprints. Grab a starter pack in one command:
+<p align="center">
+  <a href="https://www.npmjs.com/package/@grainulation/silo"><img src="https://img.shields.io/npm/v/@grainulation/silo" alt="npm version"></a> <a href="https://www.npmjs.com/package/@grainulation/silo"><img src="https://img.shields.io/npm/dm/@grainulation/silo" alt="npm downloads"></a> <a href="https://github.com/grainulation/silo/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@grainulation/silo" alt="node"></a> <a href="https://github.com/grainulation/silo/actions"><img src="https://github.com/grainulation/silo/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://deepwiki.com/grainulation/silo"><img src="https://deepwiki.com/badge.svg" alt="Explore on DeepWiki"></a>
+</p>
+
+<p align="center"><strong>Reusable knowledge for research sprints.</strong></p>
+
+Instead of starting every sprint from scratch, pull in battle-tested constraint sets, risk patterns, and decision templates. Grab a starter pack in one command:
 
 ```bash
 npx @grainulation/silo pull compliance --into ./claims.json
 ```
 
-## What is Silo?
-
-Silo stores and shares research knowledge across projects and teams. Instead of starting every sprint from scratch, pull in battle-tested constraint sets, risk patterns, and decision templates.
+## Install
 
-- **Shared claim libraries** -- reusable constraint sets (HIPAA, SOC 2, GDPR, etc.)
-- **Community sprint templates** -- pre-built research questions with seeded claims
-- **Claim import/export** -- pull claims from one sprint into another
-- **Knowledge packs** -- version-controlled bundles teams can subscribe to
-- **Full-text search** -- find relevant claims across everything you've stored
+```bash
+npm install -g @grainulation/silo
+```
 
-Zero dependencies. Filesystem-based storage. Works offline.
+## Built-in packs
 
-## Built-in Packs
+11 knowledge packs with 131 curated claims:
 
-| Pack | Claims | What's inside |
-|------|--------|---------------|
-| `api-design` | 13 | REST conventions, versioning, pagination, error formats, GraphQL tradeoffs |
-| `architecture` | 12 | Monolith vs micro, build vs buy, SQL vs NoSQL decision claims |
-| `ci-cd` | 12 | CI/CD pipeline patterns, caching, rollback strategies |
-| `compliance` | 14 | HIPAA, SOC 2, GDPR constraint sets with regulatory citations |
-| `data-engineering` | 12 | ETL patterns, data quality, warehouse design |
-| `frontend` | 12 | Frontend architecture, performance, accessibility patterns |
-| `migration` | 10 | Database/cloud/framework migration risks and patterns |
-| `observability` | 12 | Logging, metrics, tracing, alerting patterns |
-| `security` | 12 | Security constraints, threat models, authentication patterns |
-| `team-process` | 12 | Team workflow, code review, incident response patterns |
-| `testing` | 10 | Testing strategies, coverage, test architecture |
+| Pack               | Claims | What's inside                                                              |
+| ------------------ | ------ | -------------------------------------------------------------------------- |
+| `api-design`       | 13     | REST conventions, versioning, pagination, error formats, GraphQL tradeoffs |
+| `architecture`     | 12     | Monolith vs micro, build vs buy, SQL vs NoSQL decision claims              |
+| `ci-cd`            | 12     | CI/CD pipeline patterns, caching, rollback strategies                      |
+| `compliance`       | 14     | HIPAA, SOC 2, GDPR constraint sets with regulatory citations               |
+| `data-engineering` | 12     | ETL patterns, data quality, warehouse design                               |
+| `frontend`         | 12     | Frontend architecture, performance, accessibility patterns                 |
+| `migration`        | 10     | Database/cloud/framework migration risks and patterns                      |
+| `observability`    | 12     | Logging, metrics, tracing, alerting patterns                               |
+| `security`         | 12     | Security constraints, threat models, authentication patterns               |
+| `team-process`     | 12     | Team workflow, code review, incident response patterns                     |
+| `testing`          | 10     | Testing strategies, coverage, test architecture                            |
 
-## Quick Start
+## Quick start
 
 ```bash
 # See available packs
@@ -56,55 +61,58 @@ silo store "q4-migration-findings" --from ./claims.json
 silo list
 ```
 
-## CLI Reference
+## CLI
 
-| Command | Description |
-|---------|-------------|
-| `silo list` | List all stored collections |
-| `silo pull <pack> --into <file>` | Pull claims into a claims file |
-| `silo store <name> --from <file>` | Store claims from a sprint |
-| `silo search <query>` | Full-text search across claims |
-| `silo packs` | List available knowledge packs |
-| `silo templates` | List saved sprint templates |
-| `silo publish <name> --collections <ids>` | Bundle collections into a pack |
-| `silo install <file>` | Install a pack from a JSON file |
+| Command                                   | Description                     |
+| ----------------------------------------- | ------------------------------- |
+| `silo list`                               | List all stored collections     |
+| `silo pull <pack> --into <file>`          | Pull claims into a claims file  |
+| `silo store <name> --from <file>`         | Store claims from a sprint      |
+| `silo search <query>`                     | Full-text search across claims  |
+| `silo packs`                              | List available knowledge packs  |
+| `silo publish <name> --collections <ids>` | Bundle collections into a pack  |
+| `silo install <file>`                     | Install a pack from a JSON file |
 
-## How It Works
+## How it works
 
-Silo uses your filesystem for storage (`~/.silo` by default). No database, no network calls, no accounts. Claims are JSON files organized by collection, indexed for search.
+Silo uses your filesystem for storage (`~/.silo` by default). No database, no network calls, no accounts.
 
-When you `pull`, Silo:
-1. Resolves the source (built-in pack or stored collection)
-2. Re-prefixes claim IDs to avoid collisions
-3. Deduplicates against existing claims in the target
-4. Merges into your claims.json
+When you `pull`, Silo re-prefixes claim IDs to avoid collisions, deduplicates against existing claims, and merges into your claims.json.
 
-When you `store`, Silo:
-1. Reads your sprint's claims.json
-2. Hashes the content for versioning
-3. Saves to `~/.silo/claims/` with metadata
-4. Updates the search index
+When you `store`, Silo hashes the content for versioning, saves to `~/.silo/claims/`, and updates the search index.
 
 ## Programmatic API
 
 ```js
-const { Store } = require('@grainulation/silo/lib/store');
-const { Search } = require('@grainulation/silo/lib/search');
-const { ImportExport } = require('@grainulation/silo/lib/import-export');
+const { Store } = require("@grainulation/silo/lib/store");
+const { Search } = require("@grainulation/silo/lib/search");
+const { ImportExport } = require("@grainulation/silo/lib/import-export");
 
 const store = new Store().init();
 const search = new Search(store);
 const io = new ImportExport(store);
 
-// Search for encryption-related claims
-const results = search.query('encryption', { type: 'constraint' });
+const results = search.query("encryption", { type: "constraint" });
+io.pull("compliance", "./claims.json");
+io.push("./claims.json", "my-sprint-findings");
+```
 
-// Pull a pack programmatically
-io.pull('compliance', './claims.json');
+## Zero dependencies
 
-// Store findings
-io.push('./claims.json', 'my-sprint-findings');
-```
+Node built-in modules only. Filesystem-based storage. Works offline.
+
+## Part of the grainulation ecosystem
+
+| Tool                                                         | Role                                                        |
+| ------------------------------------------------------------ | ----------------------------------------------------------- |
+| [wheat](https://github.com/grainulation/wheat)               | Research engine -- grow structured evidence                 |
+| [farmer](https://github.com/grainulation/farmer)             | Permission dashboard -- approve AI actions in real time     |
+| [barn](https://github.com/grainulation/barn)                 | Shared tools -- templates, validators, sprint detection     |
+| [mill](https://github.com/grainulation/mill)                 | Format conversion -- export to PDF, CSV, slides, 24 formats |
+| **silo**                                                     | Knowledge storage -- reusable claim libraries and packs     |
+| [harvest](https://github.com/grainulation/harvest)           | Analytics -- cross-sprint patterns and prediction scoring   |
+| [orchard](https://github.com/grainulation/orchard)           | Orchestration -- multi-sprint coordination and dependencies |
+| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI -- single entry point to the ecosystem          |
 
 ## License