@tloncorp/tlon-skill 0.3.5 → 0.4.0

package/README.md

@@ -122,6 +122,17 @@ tlon contacts update-profile --nickname "My Name"
 
 # Create a group
 tlon groups create "My Group" --description "A cool group"
+
+# Create a group for a bot owner
+tlon groups create-owned "My Group" --owner ~owner-ship --description "A cool group"
+
+# Join a public or invited group; private groups without an invite request one
+tlon groups join ~host/group-slug
+
+# Manage group invite flow explicitly
+tlon groups request-invite ~host/group-slug
+tlon groups accept-invite ~host/group-slug
+tlon groups reject-invite ~host/group-slug
 ```
 
 ## Features
@@ -129,7 +140,7 @@ tlon groups create "My Group" --description "A cool group"
 - **Activity**: Mentions, replies, unreads (with nicknames)
 - **Channels**: List DMs, group DMs, subscribed groups (nicknames shown), reader/writer permissions
 - **Contacts**: List, get, update profiles
-- **Groups**: Create, join, invite, roles, privacy (member nicknames shown)
+- **Groups**: Create, join, invite/request flows, roles, privacy (member nicknames shown)
 - **Hooks**: Manage channel hooks (add, edit, delete, order, config, cron)
 - **Messages**: History, search (author nicknames shown)
 - **DMs**: Send, react, accept/decline

package/SKILL.md

@@ -11,6 +11,30 @@ Use the `tlon` command for reading data, managing channels/groups/contacts, and
 
 When running as an OpenClaw skill, use the built-in `message` tool for sending outbound messages (DMs and channel posts). The `tlon` command is for reading data, administration, and management — not for sending messages. The `message` tool routes through the proper delivery infrastructure (threading, bot profile, rate limiting).
 
+### Diary / Notebook Thread Replies
+
+Tlon diary/notebook channels are special: a channel-level `send` creates a **new notebook post/note**. Do **not** use `message` with `action: "send"` in a diary channel unless you intentionally want to create a new notebook post.
+
+For normal conversation inside an existing diary/notebook post, use the `message` tool with `action: "reply"` and reply to the **parent diary post id**, not the newest reply id.
+
+Working pattern:
+
+```json
+{
+  "action": "reply",
+  "channel": "tlon",
+  "target": "diary/~host/slug",
+  "messageId": "170.141.184.507.950.303.933.087.606.997.052.817.408",
+  "message": "Reply text here"
+}
+```
+
+Important details:
+- Use the dotted `@ud` post id format when available.
+- `messageId` should be the parent notebook post/thread id.
+- After sending, verify with `tlon messages post <diary-nest> <parent-post-id>` when correctness matters.
+- If the tool reports success but the reply is not visible under the parent post, treat it as a delivery/plugin issue and do not claim success until verified.
+
 ## Installation
 
 **npm (Node.js):**
@@ -204,18 +228,25 @@ Full group management.
 tlon groups list                                         # List your groups
 tlon groups info ~host/slug                              # Get group details
 tlon groups create "Name" [--description "..."]          # Create a group
-tlon groups join ~host/slug                              # Join a group
+tlon groups create-owned "Name" --owner ~ship [--description "..."] # Create group, invite owner, make owner admin
+tlon groups join ~host/slug                              # Join public/invited group, or request invite if private
+tlon groups request-invite ~host/slug                    # Request invite to a private group
+tlon groups accept-invite ~host/slug                     # Accept an existing group invite
+tlon groups reject-invite ~host/slug                     # Reject an existing group invite
+tlon groups cancel-join ~host/slug                       # Cancel a pending join
+tlon groups rescind-request ~host/slug                   # Cancel an invite request
 tlon groups leave ~host/slug                             # Leave a group
 tlon groups delete ~host/slug                            # Delete (host only)
 tlon groups update ~host/slug --title "..." [--description "..."]
 
 # Members (shown with nicknames when available)
 tlon groups invite ~host/slug ~ship1 ~ship2              # Invite members
+tlon groups revoke-invite ~host/slug ~ship1              # Revoke pending member invite
 tlon groups kick ~host/slug ~ship1                       # Kick members
 tlon groups ban ~host/slug ~ship1                        # Ban members
 tlon groups unban ~host/slug ~ship1                      # Unban members
-tlon groups accept-join ~host/slug ~ship1                # Accept join request
-tlon groups reject-join ~host/slug ~ship1                # Reject join request
+tlon groups accept-join ~host/slug ~ship1                # Approve a member join request
+tlon groups reject-join ~host/slug ~ship1                # Deny a member join request
 tlon groups set-privacy ~host/slug public|private|secret # Set privacy
 
 # Roles
@@ -257,6 +288,12 @@ tlon groups add-channel --help
 
 Group format: `~host-ship/group-slug`
 
+Join behavior:
+- `join` first checks whether you are already a member, then checks foreign/unjoined group state for a valid invite.
+- Invited groups and public groups use the backend join action.
+- Private groups without an invite use the invite-request action.
+- Secret groups require an invite.
+
 ### Hooks
 
 Manage channel hooks — functions that run on triggers (posts, replies, reactions, crons).
@@ -366,7 +403,7 @@ Manage channel posts (reactions, edits, deletes).
 tlon posts react chat/~host/slug 170.141... "👍"         # React to a post
 tlon posts unreact chat/~host/slug 170.141...            # Remove reaction
 tlon posts edit chat/~host/slug 170.141... "New text"    # Edit with plain text
-tlon posts edit diary/~host/slug 170.141... --title "T" --image <url> --content rich.json  # Edit notebook
+tlon posts edit diary/~host/slug 170.141... --title "T" --image <url> --content story.json # Edit notebook
 tlon posts delete chat/~host/slug 170.141...             # Delete a post
 ```
 
@@ -378,11 +415,36 @@ Post to diary/notebook channels.
 
 ```bash
 tlon notebook diary/~host/slug "Title"                   # Post with no body
-tlon notebook diary/~host/slug "Title" --content rich.json  # Post with Story JSON
+tlon notebook diary/~host/slug "Title" --content story.json # Post with Story JSON
+tlon notebook diary/~host/slug "Title" --markdown post.md   # Post with Markdown
+cat post.md | tlon notebook diary/~host/slug "Title" --markdown-stdin
 tlon notebook diary/~host/slug "Title" --image <url>     # Post with cover image
 ```
 
-The `--content` file should be Story JSON format (array of verses with headers, code blocks, formatting). See the [Story types in tlon-apps](https://github.com/tloncorp/tlon-apps/blob/develop/packages/shared/src/urbit/content.ts).
+The `--content` file should be **Urbit Story JSON**: an array of verses accepted by the ship's `story-json` decoder. Use `--markdown` for Markdown files instead of passing Markdown or editor-export JSON through `--content`.
+
+Working examples:
+
+```json
+[{"inline": ["Hello world"]}]
+```
+
+```json
+[{"block": {"header": {"tag": "h1", "content": ["Title"]}}}]
+```
+
+```json
+[{"inline": ["Use ", {"inline-code": "ha-q"}, " for entity queries."]}]
+```
+
+Important gotcha:
+- Do **not** assume newer block-editor JSON shapes or arbitrary markdown-export JSON will work.
+- If posting fails with a `channel-action-2` cast error mentioning `content -> add -> post -> action -> channel`, the first thing to check is whether the content file matches the ship's Story JSON shape.
+- When debugging, post a minimal one-verse story first so you do not create duplicate full notebook posts.
+
+See the ship-side decoder and types here:
+- `tlon-apps/desk/lib/story-json.hoon`
+- [Story types in tlon-apps](https://github.com/tloncorp/tlon-apps/blob/develop/packages/shared/src/urbit/content.ts)
 
 ### Upload
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tloncorp/tlon-skill",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Tlon/Urbit skill for OpenClaw agents",
   "type": "module",
   "bin": {
@@ -21,10 +21,10 @@
     "postinstall": "node scripts/postinstall.js"
   },
   "optionalDependencies": {
-    "@tloncorp/tlon-skill-darwin-arm64": "0.3.5",
-    "@tloncorp/tlon-skill-darwin-x64": "0.3.5",
-    "@tloncorp/tlon-skill-linux-x64": "0.3.5",
-    "@tloncorp/tlon-skill-linux-arm64": "0.3.5"
+    "@tloncorp/tlon-skill-darwin-arm64": "0.4.0",
+    "@tloncorp/tlon-skill-darwin-x64": "0.4.0",
+    "@tloncorp/tlon-skill-linux-x64": "0.4.0",
+    "@tloncorp/tlon-skill-linux-arm64": "0.4.0"
   },
   "devDependencies": {
     "@tloncorp/api": "^0.0.4",