agent build

knowledge/README.md

@@ -0,0 +1,37 @@
+# Documents agents can read
+
+Markdown files, one per document, ingested by:
+
+    make ingest ORG=<slug>
+
+Each file declares who may read it in its front matter. **That declaration is
+required** — §5 says a chunk without ACL metadata is rejected at ingest, and the
+reason is worth stating: an empty audience is not "private", it is a row the
+permission filter can never match. A document that indexed to nothing looks
+ingested, reports a chunk count, and is silently unreachable forever.
+
+```markdown
+---
+source: policy_docs
+audience: tenant          # everyone in the organization
+title: Staff Handbook
+---
+```
+
+`audience` accepts:
+
+| value | who can read it |
+|---|---|
+| `tenant` | everyone in the organization |
+| `role:admin`, `role:employer`, `role:talent` | one role (comma-separate for several) |
+| `email:someone@example.com` | one person, by email |
+
+`source` is the corpus name. An agent spec's `sources:` block names which
+corpora it may retrieve from, so this is part of the permission story rather
+than a label: an agent granted `policy_docs` does not thereby gain
+`worker_notes`.
+
+Re-ingesting is safe. A document whose content and audience are unchanged is a
+no-op; changing either rewrites its chunks, because the chunks carry a copy of
+the audience and a permission change that did not reach them would be a
+permission change that did not happen.