@tloncorp/tlon-skill 0.3.4 → 0.3.6

package/README.md

@@ -104,6 +104,13 @@ tlon --url https://bot.tlon.network --cookie "urbauth-~bot=0v..." contacts self
 # List your groups
 tlon channels groups
 
+# Create a group channel
+# (preferred alias; tlon groups add-channel still works)
+tlon channels create ~host/group-slug "Projects" --kind chat
+
+# Rename a channel
+tlon channels rename chat/~host/project-updates "Team Updates"
+
 # Get recent mentions
 tlon activity mentions --limit 10
 
@@ -115,6 +122,14 @@ tlon contacts update-profile --nickname "My Name"
 
 # Create a group
 tlon groups create "My Group" --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
@@ -122,7 +137,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):**
@@ -150,6 +174,8 @@ tlon channels dms                                          # List DM contacts (w
 tlon channels groups                                       # List subscribed groups
 tlon channels all                                          # List everything
 tlon channels info chat/~host/slug                         # Get channel details
+tlon channels create ~host/slug "Projects" --kind chat     # Create a group channel
+tlon channels rename chat/~host/slug "New Title"           # Rename a channel
 tlon channels update chat/~host/slug --title "New Title"   # Update metadata
 tlon channels delete chat/~host/slug                       # Delete a channel
 
@@ -162,6 +188,14 @@ tlon channels add-readers ~host/group chat/~host/slug admin    # Restrict viewin
 tlon channels del-readers ~host/group chat/~host/slug admin    # Open viewing
 ```
 
+Help works for both the command and subcommands:
+
+```bash
+tlon channels --help
+tlon channels create --help
+tlon channels rename --help
+```
+
 Notes on permissions:
 
 - Empty writers list = anyone in the group can post (default for chat)
@@ -194,18 +228,24 @@ 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 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
@@ -232,8 +272,27 @@ Roles vs Admin:
 tlon groups add-channel ~host/slug "Name" [--kind chat|diary|heap]
 ```
 
+`tlon groups add-channel` remains supported, but for agent/tool use prefer the more discoverable channel-centric form:
+
+```bash
+tlon channels create ~host/slug "Projects" --kind chat
+```
+
+Help works here too:
+
+```bash
+tlon groups --help
+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).
@@ -343,7 +402,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
 ```
 
@@ -355,11 +414,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.4",
+  "version": "0.3.6",
   "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.4",
-    "@tloncorp/tlon-skill-darwin-x64": "0.3.4",
-    "@tloncorp/tlon-skill-linux-x64": "0.3.4",
-    "@tloncorp/tlon-skill-linux-arm64": "0.3.4"
+    "@tloncorp/tlon-skill-darwin-arm64": "0.3.6",
+    "@tloncorp/tlon-skill-darwin-x64": "0.3.6",
+    "@tloncorp/tlon-skill-linux-x64": "0.3.6",
+    "@tloncorp/tlon-skill-linux-arm64": "0.3.6"
   },
   "devDependencies": {
     "@tloncorp/api": "^0.0.4",