Write down the useful part

Save discoveries with enough explanation and evidence for someone else to use them.

Lore is coming soon. These guides describe the upcoming release.

Lore

Explain what matters and why

Choose a category: gotcha, architecture, business-rule, convention, or decision. Give the entry a short summary and an explanation that makes sense on its own.

Save the example as discovery.json. Replace REPLACE_WITH_PROJECT_UUID with the ID from zedbee-lore projects list. Replace the author and evidence with the real source. The example is illustrative, not a claim about your project.

{
  "schemaVersion": 1,
  "category": "gotcha",
  "summary": "Preserve provider identifiers",
  "explanation": "Changing their format can create duplicate imports during reconciliation.",
  "audience": "project",
  "bindings": [
    {
      "projectId": "REPLACE_WITH_PROJECT_UUID",
      "scopes": [
        {
          "kind": "folder",
          "path": "src/jobs"
        }
      ]
    }
  ],
  "author": "Your name",
  "evidence": [
    {
      "kind": "test",
      "reference": "test/import.test.ts"
    }
  ]
}

Lore

Submit and review the discovery

The current release accepts entries as JSON files or through MCP. In the default review mode, a new discovery is pending. Review the evidence before accepting it.

The add command returns the entry ID and revision. Substitute those real values in the review command. Review capture does not interrupt an agent to ask about every entry.

zedbee-lore add --input discovery.json
zedbee-lore list --state pending
zedbee-lore review accept ENTRY_ID --revision 1 --reason "Checked the cited test"

Lore

Choose how submissions become active

Review mode keeps new discoveries pending. Automatic mode makes ordinary submitted discoveries active immediately. Possible permission or prohibition statements can still remain pending for review.

Automatic refers to how submissions are handled. Lore does not monitor sessions to create entries by itself.

zedbee-lore config set capture automatic --project PROJECT_ID
zedbee-lore config set capture review --project PROJECT_ID

Lore

Update an entry without losing its history

An update includes a version number, the entry ID, its current revision as expectedRevision, and the complete replacement draft. Use the example below to put those parts in the right place.

If someone has already changed the entry, Lore rejects the out-of-date edit instead of silently overwriting it. Read the latest entry, check the changes, and submit a revised update.

Use retire when knowledge no longer applies. Keep instructions and permission rules in your instruction files.

zedbee-lore show ENTRY_ID
zedbee-lore history ENTRY_ID
zedbee-lore update --input revision.json
zedbee-lore retire ENTRY_ID --revision 2 --reason "The integration was removed"

Lore

Prepare the replacement entry

Save this as revision.json. Replace the entry and project IDs with the real IDs, set expectedRevision to the current revision from show, and fill in the complete entry you want to keep.

schemaVersion belongs at the top level of the request. The replacement fields belong inside draft, without an entry ID, revision, or version field of their own.

Run zedbee-lore update --input revision.json to submit it. If the current revision has changed, read the newer entry and check your changes before trying again.

{
  "schemaVersion": 1,
  "id": "REPLACE_WITH_ENTRY_UUID",
  "expectedRevision": 1,
  "draft": {
    "category": "gotcha",
    "summary": "Preserve provider identifiers",
    "explanation": "Keep identifiers unchanged when importing and reconciling provider records to avoid duplicate imports.",
    "audience": "project",
    "bindings": [
      {
        "projectId": "REPLACE_WITH_PROJECT_UUID",
        "scopes": [
          {
            "kind": "folder",
            "path": "src/jobs"
          }
        ]
      }
    ],
    "author": "Your name",
    "evidence": [
      {
        "kind": "test",
        "reference": "test/import.test.ts"
      }
    ]
  }
}