Skip to content

docs: add Schema + Record and Language support guides #300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cmeans-claude-dev merged 6 commits into from
Apr 16, 2026
Merged

docs: add Schema + Record and Language support guides #300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f73aae5
docs: add Schema + Record user guide
Apr 16, 2026
0ea4237
docs: add Language support guide
Apr 16, 2026
34a89f4
fix: address QA findings + add Mermaid diagrams to guides
Apr 16, 2026
745772f
fix: language guide — TOC, embedding languages, detailed search diagram
Apr 16, 2026
0b738f0
fix: language guide — replace 3-column table, add XLM-R list, credit …
Apr 16, 2026
6bae9e0
fix: address round 5 QA findings on docs
Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]

### Added
- **Schema + Record user guide** — new `docs/schema-record-guide.md` walks through why typed data matters, a full music-collection worked example (register schema → create record → validation failure → update → delete blocked), the Tag Taxonomy (Layer C) tie-in, and six collapsible use cases: reading list, recipes, home inventory, subscriptions, edge provider manifests, meeting/bug templates. Linked from README "Design docs". README also updates the CLI tools list to include `mcp-awareness-register-schema`.
- **Language support guide** — new `docs/language-guide.md` covers per-entry language detection (explicit parameter or auto-detect via lingua), supported languages (28 Postgres snowball regconfigs), querying by language (`get_knowledge` language filter), how hybrid search handles cross-language queries, unsupported-language alerts as a demand signal, and deployment notes (lingua install, backfill migration, regconfig validation cache). Linked from README "Design docs".
- **CLA bot** — installed [CLA Assistant](https://cla-assistant.io) to gate pull requests on a signed Contributor License Agreement. New `CLA.md` (v1.0) at the repo root holds the authoritative text (dual-license sublicensing grant, no copyright transfer). New `docs/cla.md` documents the bot, the signature record location (a public Gist owned by the maintainer), and the maintainer/bot whitelist. `CONTRIBUTING.md` "How to sign" section rewritten with the concrete signing flow. Refs [#297](https://github.com/cmeans/mcp-awareness/issues/297) (end-to-end verification against a non-maintainer account remains open).
- Two new entry types: `schema` (JSON Schema Draft 2020-12 definition) and `record` (validated payload conforming to a schema). Tools: `register_schema`, `create_record`. Schemas are absolutely immutable after registration; records re-validate on content update. Schema deletion is blocked while live records reference a version. Per-owner storage with a shared `_system` fallback namespace for built-in schemas.
- New CLI: `mcp-awareness-register-schema` for operators to seed `_system`-owned schemas at deploy time.
Expand Down
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -354,7 +354,7 @@ For single-user deployments, secret path + WAF is sufficient. For multi-user, en
- **One-line demo install** — `curl | bash` sets up Awareness + Postgres + Cloudflare quick tunnel with pre-loaded demo data and a `getting-started` prompt that personalizes your instance
- **Published Docker images** — `ghcr.io/cmeans/mcp-awareness` (GHCR) and Docker Hub, auto-built on release tags
- **Optional embedding provider** — add `AWARENESS_EMBEDDING_PROVIDER=ollama` and `docker compose --profile embeddings up -d` to enable the vector branch of hybrid search. FTS works without it
- **CLI tools** — `mcp-awareness-user` (user management), `mcp-awareness-token` (JWT generation), `mcp-awareness-secret` (signing secret generation)
- **CLI tools** — `mcp-awareness-user` (user management), `mcp-awareness-token` (JWT generation), `mcp-awareness-secret` (signing secret generation), `mcp-awareness-register-schema` (seed `_system`-owned schemas at deploy time)

### Knowledge store
- `remember`, `learn_pattern`, `add_context`, `set_preference` with filtered retrieval
Expand Down Expand Up @@ -462,6 +462,8 @@ Read the full vision: **[What Knowledge Becomes When It's Ambient](docs/vision.m
- [From Metrics to Mental Models](docs/from-metrics-to-mental-models.md) — core spec: three-layer detection model, API design, data schema
- [Collation Layer](docs/collation-layer.md) — briefing resource, token optimization, escalation logic
- [Data Dictionary](docs/data-dictionary.md) — database schema, entry types, data field structures, lifecycle rules
- [Schema + Record Guide](docs/schema-record-guide.md) — how to define typed data contracts with JSON Schema, with worked examples (music collection, reading list, recipes, home inventory, subscriptions, edge manifests, tag taxonomy)
- [Language Support Guide](docs/language-guide.md) — per-entry language detection, language-specific FTS stemming, supported languages, querying by language, unsupported-language alerts, deployment notes
- [Memory Prompts](docs/memory-prompts.md) — how to configure your AI to use awareness (platform memory, global CLAUDE.md, project CLAUDE.md)
- [Changelog](CHANGELOG.md) — version history

Expand Down
Loading