denchclaw 2.4.3 → 2.4.5

package/skills/crm/documents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: documents
-description: Document management with markdown files, cross-nesting between documents and objects, and human-readable entry detail pages linked through the documents table.
+description: Document management with markdown files, always-on entry documents linked through the documents table, and mutation/edit logs for CRM entries. Use when creating or updating row notes, entry notes, detail pages, or document-linked CRM content.
 metadata: { "openclaw": { "inject": true, "always": true, "emoji": "📄" } }
 ---
 
@@ -14,6 +14,18 @@ This skill covers document management, cross-nesting, and entry detail pages. Fo
 
 Documents are markdown files in `{{WORKSPACE_PATH}}/**`. The DuckDB `documents` table tracks metadata only; the `.md` file IS the content.
 
+## Default Rule: Every Entry Needs a Connected Document
+
+Treat the entry document as the default long-form companion to the row.
+
+Mandatory defaults:
+
+- Create or reuse a connected entry document whenever you create an entry and have enough information to derive a sane filename/title.
+- When updating an entry, ensure a connected document exists before finishing the task. If it is missing, create it.
+- Keep the document registered in DuckDB `documents` with `entry_id`, `parent_object_id`, and `file_path`.
+- If the user asks to add or change anything on an entry, update the connected document too.
+- Append a concise timestamped activity log entry for every meaningful mutation so the document acts as an edit log, not just a static page.
+
 ### Create Document
 
 1. Write the `.md` file: `write {{WORKSPACE_PATH}}/projects/roadmap.md`
@@ -41,12 +53,14 @@ These are **not the same thing**:
 When the user says:
 
 - "fill in notes for each entry"
+- "add notes to this row"
+- "add a note to this entry"
 - "write descriptions for all rows"
 - "add detailed writeups"
 - "put the outreach draft into each influencer notes page"
 - "create entry docs"
 
-default to **entry documents** unless they explicitly say "update the Notes column/field".
+default to the **connected entry document**.
 
 If the user truly means the `Notes` field, they will usually talk about:
 
@@ -55,6 +69,8 @@ If the user truly means the `Notes` field, they will usually talk about:
 - filtering/sorting by Notes
 - SQL updates to `entry_fields`
 
+If they explicitly ask to update the `Notes` field/column, update that DuckDB value **and** sync the connected entry document unless they clearly ask you not to.
+
 If they mean entry documents, they are talking about:
 
 - markdown pages
@@ -66,7 +82,7 @@ If they mean entry documents, they are talking about:
 
 ## Entry Detail Pages
 
-Each entry in an object can have an optional markdown file that acts as its detail page in the entry panel.
+Each entry in an object should have a markdown file that acts as its detail page and running edit log in the entry panel.
 
 **CRITICAL:** New entry documents should use **human-readable filenames**, not raw UUID filenames. The file must also be registered in DuckDB `documents` with `entry_id`, `parent_object_id`, and `file_path`.
 
@@ -74,8 +90,20 @@ Each entry in an object can have an optional markdown file that acts as its deta
 
 For every entry document:
 
-1. Write a human-readable markdown file inside the object directory
-2. Insert/update a row in `documents` linking the entry to that file
+1. Reuse the existing linked document if one already exists for the entry
+2. Otherwise write a human-readable markdown file inside the object directory
+3. Insert/update a row in `documents` linking the entry to that file
+4. Update the markdown content and append the mutation log entry
+
+Before creating a new file, resolve any existing document:
+
+```sql
+SELECT id, title, file_path
+FROM documents
+WHERE entry_id = '<entry_id>'
+ORDER BY updated_at DESC
+LIMIT 1;
+```
 
 ```sql
 INSERT INTO documents (title, file_path, parent_object_id, entry_id)
@@ -127,6 +155,27 @@ Examples:
 - `Creator Name = Jane Smith` -> `jane-smith-001.md`
 - `Company Name = Acme Corp` -> `acme-corp-001.md`
 
+### Default content model
+
+Keep the entry document readable for humans and useful as an audit trail. A good default shape is:
+
+```markdown
+# Jane Smith
+
+## Summary
+Current state of the entry in plain English.
+
+## Notes
+User-facing notes, drafts, follow-ups, or other long-form details.
+
+## Activity Log
+### 2026-03-30T12:34:56Z - Entry updated
+- Changed `Status`: `New` -> `Qualified`
+- Added note: Follow up on Thursday about pricing
+```
+
+Update the current sections in place and append new log items instead of rewriting history.
+
 ### NEVER do these
 
 - Do **NOT** default to `{entry_id}.md` for new documents
@@ -142,7 +191,7 @@ Older workspaces may still have legacy `{entry_id}.md` files. Those can continue
 
 ## Creating One Entry Document
 
-Only create entry `.md` files when the user wants detailed prose for a specific entry or group of entries.
+Create or repair the connected entry `.md` file whenever the user creates an entry, mentions notes on the row/entry, or makes a mutation and no document exists yet.
 
 Example:
 
@@ -182,7 +231,7 @@ SET title = excluded.title,
 
 ## Batch Creating Entry Documents
 
-When the user asks for docs for many entries, do **not** update the `Notes` field in SQL. Create markdown files plus `documents` rows.
+When the user asks for docs for many entries, or asks to add notes/details across many entries, create/update markdown files plus `documents` rows. Only update the `Notes` field in SQL when they explicitly want that field changed too.
 
 ### Workflow
 
@@ -190,6 +239,7 @@ When the user asks for docs for many entries, do **not** update the `Notes` fiel
 2. Derive a human-readable filename for each entry
 3. Write one `.md` file per entry under the object directory
 4. Insert/update one `documents` row per file
+5. Append or update each file's `## Notes` and `## Activity Log` sections to capture the requested changes
 
 ### Example: create docs for every influencer
 
@@ -253,3 +303,19 @@ Examples:
 - `marketing/influencer/outreach-playbook.md` with no `entry_id` -> standalone object-level document
 
 If a markdown file is meant to be the entry page, always register it in `documents`.
+
+## Sync on Entry Mutations
+
+After **any** meaningful entry mutation:
+
+1. Resolve the linked entry document by `documents.entry_id`
+2. Create the document if it does not exist yet
+3. Update the relevant prose sections (`Summary`, `Notes`, drafts, follow-ups, etc.)
+4. Append a timestamped `Activity Log` entry describing the delta
+
+This applies to:
+
+- field value changes
+- explicit `Notes` field updates
+- status/owner/priority changes
+- user requests to "add", "note", "log", "remember", or otherwise attach information to an entry

package/skills/crm/duckdb-operations/SKILL.md

@@ -210,7 +210,7 @@ Important:
 
 **enum fields**: Field definition stores `enum_values` as JSON array. Entry stores the selected value string. `enum_multiple = true` for multi-select (value stored as JSON array string).
 
-**relation fields**: Field stores `related_object_id` (the ID of the target object) and `relationship_type` (`many_to_one` for single select, `many_to_many` for multi-select). Entry field value stores the related entry ID (or JSON array of IDs for many-to-many). Relation fields can only be created via direct DuckDB SQL (not the API). The UI renders them as a searchable dropdown of entries from the related object.
+**relation fields**: Field stores `related_object_id` (the ID of the target object) and `relationship_type` (`many_to_one` for single select, `many_to_many` for multi-select). Entry field value stores the related entry ID (or JSON array of IDs for many-to-many). Relation fields can only be created via direct DuckDB SQL (not the API). The UI renders them as a searchable dropdown of entries from the related object. This is the default for foreign-table, lookup, linked-record, or "connect this column to another table" requests. Do **NOT** use `text`/`richtext` to store another object's label when a real linked object exists.
 
 Creating a relation field (SQL — the only way):
 
@@ -257,6 +257,8 @@ ON CONFLICT (name) DO NOTHING RETURNING *;
 
 ### Create Fields
 
+Use this only for scalar fields. If the field is meant to reference another object/table, skip this section and use **Create Relation Field** instead.
+
 ```sql
 INSERT INTO fields (object_id, name, type, required, sort_order)
 VALUES
@@ -281,6 +283,16 @@ VALUES (
 
 Relation fields link entries across objects. **You MUST create these via SQL** — the API does not support `relation` type.
 
+Use a relation field by default when:
+
+- the user says the column should connect/link/reference another table or object
+- the field name matches or strongly aliases an existing object
+- the column is really a lookup/select field rather than free-form text
+
+Do **NOT** create surrogate string columns like `Company Name`, `Client Name`, `Deal Name`, `Project Name`, or similar when the corresponding object already exists, unless the user explicitly wants denormalized snapshot text.
+
+Default to `many_to_one`. Use `many_to_many` only for clearly plural or multi-select relationships.
+
 ```sql
 -- Link people → company (many people belong to one company)
 INSERT INTO fields (object_id, name, type, related_object_id, relationship_type, sort_order)
@@ -367,6 +379,8 @@ COMMIT;
 "
 ```
 
+Entry creation is not complete until the connected entry document exists on disk and is registered in `documents`. After the SQL commit, follow the default sync workflow in `crm/documents/SKILL.md`.
+
 ### Search Entries (via view)
 
 ```sql
@@ -391,6 +405,8 @@ VALUES ('<entry_id>', (SELECT id FROM fields WHERE object_id = '<obj_id>' AND na
 ON CONFLICT (entry_id, field_id) DO UPDATE SET value = excluded.value, updated_at = now();
 ```
 
+After updating `entry_fields`, immediately sync the connected entry document and append a timestamped activity log entry describing the change. This still applies when the user explicitly asks for the `Notes` field/column.
+
 ### Delete (with cascade)
 
 ```sql

package/skills/crm/object-builder/SKILL.md

@@ -197,7 +197,24 @@ EOF
 
 ## Proactive Relation Creation (IMPORTANT)
 
-**When creating multiple objects, ALWAYS create relation fields to link them — even if the user did not explicitly ask for it.** Real-world data is interconnected. If two objects are obviously related, link them. The user expects this; not linking them is a missed opportunity that forces manual work later.
+**When creating multiple objects or adding fields to an existing object, ALWAYS create relation fields to link them — even if the user did not explicitly ask for it.** Real-world data is interconnected. If two objects are obviously related, link them. The user expects this; not linking them is a missed opportunity that forces manual work later.
+
+### Foreign-link default for new columns
+
+Before you create any new field on an object:
+
+1. Run `SELECT name FROM objects ORDER BY name`
+2. Check whether the requested field is really a foreign link to one of those objects
+3. If yes, create a `relation` field via SQL instead of a scalar field via API/text defaults
+4. Regenerate the PIVOT view and update `.object.yaml` so the linked field is reflected everywhere
+
+Aggressive defaults:
+
+- If the user says the field should connect to another table/object, create a `relation` field.
+- If the field name matches or strongly aliases an existing object, create a `relation` field.
+- If the field refers to a workspace member, use `user`, not `text`.
+- Do **NOT** create fallback text columns like `Company Name`, `Client Name`, `Project Name`, `Deal Name`, or `Owner Name` when the real object already exists, unless the user explicitly asks for a copied text snapshot.
+- Default to `many_to_one`; switch to `many_to_many` only when the field is clearly plural or multi-select.
 
 ### When to create relations automatically
 
@@ -212,7 +229,7 @@ EOF
 - **Property + Agent** → add "Agent" relation on property (many_to_one → people)
 - **Any child object + parent object** → link child to parent
 
-**General rule**: If you're creating object B and object A already exists (or is being created alongside), ask yourself: "Would an entry in B logically belong to or reference an entry in A?" If yes, add a relation field.
+**General rule**: If you're creating object B, or adding field F to object B, and object A already exists (or is being created alongside), ask yourself: "Would an entry in B logically belong to, reference, select, or connect to an entry in A?" If yes, add a relation field.
 
 ### Relation field SQL pattern
 
@@ -232,6 +249,15 @@ Use `many_to_one` when each entry links to exactly one entry in the other object
 
 **Relation fields must be created via SQL** — the API does not support the `relation` type.
 
+### Bad vs Good defaults
+
+- Bad: add `Company Name` as `text` on `lead` when `company` already exists
+- Good: add `Company` as `relation -> company`
+- Bad: add `Project` as `text` on `task` when `project` already exists
+- Good: add `Project` as `relation -> project`
+- Bad: add `Owner Name` as `text` when the value should be a team member selector
+- Good: add `Owner` / `Assigned To` as `user`
+
 ---
 
 ## CRM Patterns