ticlawk 0.1.16-dev.3 → 0.1.16-dev.30

package/src/core/argv.mjs

@@ -29,7 +29,17 @@ export function parseOptionArgs(argv = []) {
       const value = inlineValue !== undefined
         ? inlineValue
         : argv[i + 1] && !argv[i + 1].startsWith('-') ? argv[++i] : true;
-      args[rawKey] = value;
+      // Repeated flags collect into an array so `--attach a --attach b`
+      // surfaces as ['a','b'] to callers that expect repeatable input
+      // (--attach on message send, --member on group create, etc).
+      // First occurrence stays scalar so single-value callers don't
+      // have to learn array-or-string.
+      if (Object.prototype.hasOwnProperty.call(args, rawKey)) {
+        const existing = args[rawKey];
+        args[rawKey] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+      } else {
+        args[rawKey] = value;
+      }
       continue;
     }
     args._.push(arg);

package/src/core/http.mjs

@@ -3,6 +3,25 @@ import {
   handleAttachmentUpload,
   handleAttachmentView,
   handleGroupCreate,
+  handleWorkstreamCharterGet,
+  handleWorkstreamCharterSet,
+  handleWorkstreamCreate,
+  handleWorkstreamDelete,
+  handleWorkstreamList,
+  handleAgentList,
+  handleAgentCreate,
+  handleAgentDelete,
+  handleWorkstreamDashboardSet,
+  handleWorkstreamDashboardGet,
+  handleCredentialRequest,
+  handleBriefingPublish,
+  handleBriefingGet,
+  handleServiceCreate,
+  handleServiceUpdate,
+  handleServiceDelete,
+  handleServiceList,
+  handleServiceInfo,
+  handleServiceCall,
   handleGroupMembers,
   handleGroupMembersAdd,
   handleGroupMembersRemove,
@@ -11,6 +30,7 @@ import {
   handleMessageRead,
   handleMessageSearch,
   handleMessageSend,
+  handleProfileAvatarUpload,
   handleProfileShow,
   handleProfileUpdate,
   handleReminderCancel,
@@ -148,6 +168,12 @@ export function startLocalHttpServer({ port, adapter, ctx }) {
         const r = await handleProfileUpdate(req, body, cliCtx);
         return writeJson(res, r.status, r.body);
       }
+      if (urlNoQuery === '/agent/profile/avatar' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleProfileAvatarUpload(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
       if (urlNoQuery === '/agent/attachment/upload' && method === 'POST') {
         const body = await readJsonBody(req);
         if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
@@ -216,6 +242,106 @@ export function startLocalHttpServer({ port, adapter, ctx }) {
         const r = await handleServerInfo(req, parseQuery(req.url || ''), cliCtx);
         return writeJson(res, r.status, r.body);
       }
+      if (urlNoQuery === '/agent/workstream/charter/get' && method === 'GET') {
+        const r = await handleWorkstreamCharterGet(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/charter/set' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamCharterSet(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/create' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamCreate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/delete' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamDelete(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/list' && method === 'GET') {
+        const r = await handleWorkstreamList(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/agent/list' && method === 'GET') {
+        const r = await handleAgentList(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/agent/create' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleAgentCreate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/agent/delete' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleAgentDelete(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/dashboard/set' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamDashboardSet(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/dashboard/get' && method === 'GET') {
+        const r = await handleWorkstreamDashboardGet(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/briefing/publish' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleBriefingPublish(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/briefing/get' && method === 'GET') {
+        const r = await handleBriefingGet(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/credential/request' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleCredentialRequest(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/create' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceCreate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/update' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceUpdate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/delete' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceDelete(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/list' && method === 'GET') {
+        const r = await handleServiceList(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/info' && method === 'GET') {
+        const r = await handleServiceInfo(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/call' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceCall(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
 
       writeJson(res, 404, { error: 'not found' });
     } catch (err) {

package/src/core/runtime-env.mjs

@@ -15,6 +15,7 @@
 const STRIPPED_KEYS = new Set([
   'TICLAWK_CONNECTOR_API_KEY',
   'TICLAWK_CONNECTOR_WS_URL',
+  'TICLAWK_CREDENTIAL_NAMES',
   'TICLAWK_SETUP_CODE',
 ]);
 
@@ -35,11 +36,17 @@ export function buildAgentRuntimeEnv({
   sessionId,
   hostId,
   daemonUrl,
+  conversationId,
+  messageId,
+  target,
 } = {}) {
   const out = {};
   if (agentId) out.TICLAWK_RUNTIME_AGENT_ID = String(agentId);
   if (sessionId) out.TICLAWK_RUNTIME_SESSION_ID = String(sessionId);
   if (hostId) out.TICLAWK_RUNTIME_HOST_ID = String(hostId);
+  if (conversationId) out.TICLAWK_RUNTIME_CONVERSATION_ID = String(conversationId);
+  if (messageId) out.TICLAWK_RUNTIME_MESSAGE_ID = String(messageId);
+  if (target) out.TICLAWK_RUNTIME_TARGET = String(target);
   out.TICLAWK_RUNTIME_DAEMON_URL = daemonUrl || 'http://127.0.0.1:8741';
   return out;
 }

package/src/core/runtime-support.mjs

@@ -3,6 +3,7 @@ import { getAgentHome } from './agent-home.mjs';
 const ERROR_MAX_CHARS = 500;
 const DEFAULT_DELTA_FLUSH_MS = 250;
 const DEFAULT_DELTA_FLUSH_CHARS = 64;
+const MAX_SCOPED_RUNTIME_SESSIONS = 50;
 
 function truncateError(text) {
   if (!text) return null;
@@ -42,36 +43,6 @@ export function shouldStreamRuntime(runtimeName, runtime) {
   return Boolean(runtime?.runTurnStream) && getStreamingMode(runtimeName);
 }
 
-export async function sendAdapterMessage(adapter, binding, payload) {
-  await adapter.send(binding, payload);
-}
-
-/**
- * Record the runtime's final turn output as activity (NOT chat).
- *
- * Previously called `sendResult` and treated as "the chat reply path".
- * After the group-chat upgrade, chat is produced exclusively by the
- * agent invoking `ticlawk message send` via the CLI. The runtime's
- * raw final output is still surfaced for trajectory/debug UI, but it
- * no longer materializes as a `messages` row — the trigger
- * `project_agent_event` was updated in PR-2b to drop the chat
- * projection.
- *
- * Renamed so the call sites read self-evidently: "record activity"
- * never reads as "send a chat message".
- */
-export async function recordActivity(adapter, binding, inbound, result) {
-  if (!result?.text && (!result?.mediaUrls || result.mediaUrls.length === 0)) return;
-  await sendAdapterMessage(adapter, binding, {
-    type: 'assistant',
-    text: result.text || '',
-    media: result.media || [],
-    turnId: inbound.messageId || result?.turnId || null,
-    replyToMessageId: inbound.messageId || null,
-  });
-}
-
-
 export async function reportSubprocessFailure({ adapter, binding, inbound, runtimeName, info }) {
   if (!info || info.ok) return;
   const seconds = ((info.durationMs || 0) / 1000).toFixed(1);
@@ -135,6 +106,106 @@ export async function updateBindingRuntimeMeta(ctx, binding, runtimeMetaPatch, e
   });
 }
 
+function readScopedSessionKey(inbound = {}) {
+  const conversationId = String(inbound?.conversationId || '').trim();
+  if (!conversationId) return '';
+  const threadRoot = String(inbound?.raw?.thread_root_message_id || '').trim();
+  return threadRoot ? `${conversationId}:thread:${threadRoot}` : conversationId;
+}
+
+function normalizeScopedRuntimeSessions(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const out = {};
+  for (const [key, session] of Object.entries(value)) {
+    if (!key || !session || typeof session !== 'object' || Array.isArray(session)) continue;
+    const sessionId = typeof session.sessionId === 'string' ? session.sessionId.trim() : '';
+    if (!sessionId) continue;
+    out[key] = {
+      sessionId,
+      path: typeof session.path === 'string' ? session.path : null,
+      lastRotatedAt: typeof session.lastRotatedAt === 'string' ? session.lastRotatedAt : null,
+      updatedAt: typeof session.updatedAt === 'string' ? session.updatedAt : null,
+    };
+  }
+  return out;
+}
+
+function pruneScopedRuntimeSessions(sessions) {
+  const entries = Object.entries(sessions);
+  if (entries.length <= MAX_SCOPED_RUNTIME_SESSIONS) return sessions;
+  return Object.fromEntries(entries
+    .sort(([, a], [, b]) => {
+      const aTs = Date.parse(a?.updatedAt || a?.lastRotatedAt || '') || 0;
+      const bTs = Date.parse(b?.updatedAt || b?.lastRotatedAt || '') || 0;
+      return bTs - aTs;
+    })
+    .slice(0, MAX_SCOPED_RUNTIME_SESSIONS));
+}
+
+export function resolveRuntimeSessionScope(meta = {}, inbound = {}) {
+  const key = readScopedSessionKey(inbound);
+  if (!key) {
+    return {
+      key: '',
+      sessions: {},
+      sessionId: meta.sessionId || null,
+      path: meta.path || null,
+      lastRotatedAt: meta.lastRotatedAt || null,
+      shouldRotate: !meta.sessionId || Boolean(meta.rotatePending),
+    };
+  }
+
+  const sessions = meta.rotatePending ? {} : normalizeScopedRuntimeSessions(meta.conversationSessions);
+  const scoped = sessions[key] || {};
+  return {
+    key,
+    sessions,
+    sessionId: scoped.sessionId || null,
+    path: scoped.path || null,
+    lastRotatedAt: scoped.lastRotatedAt || null,
+    shouldRotate: !scoped.sessionId || Boolean(meta.rotatePending),
+  };
+}
+
+export function buildRuntimeSessionMetaPatch(meta = {}, scope = {}, result = {}) {
+  const now = new Date().toISOString();
+  const scoped = Boolean(scope.key);
+  const sessionId = result?.sessionId || scope.sessionId || (scoped ? null : meta.sessionId || null);
+  const path = result?.path || scope.path || (scoped ? null : meta.path || null);
+  const lastRotatedAt = scope.shouldRotate
+    ? now
+    : (scope.lastRotatedAt || meta.lastRotatedAt || now);
+
+  if (!scoped) {
+    return {
+      sessionId,
+      ...(path !== undefined ? { path } : {}),
+      rotatePending: false,
+      lastRotatedAt,
+    };
+  }
+
+  const sessions = {
+    ...(scope.sessions || {}),
+  };
+  if (sessionId) {
+    sessions[scope.key] = {
+      sessionId,
+      path,
+      lastRotatedAt,
+      updatedAt: now,
+    };
+  }
+
+  return {
+    sessionId,
+    path,
+    conversationSessions: pruneScopedRuntimeSessions(sessions),
+    rotatePending: false,
+    lastRotatedAt,
+  };
+}
+
 export function createDeltaAggregator({
   flushDelta,
   flushMs = DEFAULT_DELTA_FLUSH_MS,

package/src/migrate/write-initial-memory.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-// Seed the slock-style per-agent home + MEMORY.md for every paired
-// agent in the linked Supabase project.
+// Seed the per-agent home + MEMORY.md for every paired agent in the
+// linked Supabase project.
 //
 //   ~/.ticlawk/agents/<agent_id>/MEMORY.md
 //
-// This replaces the Phase-B variant that wrote MEMORY.md into each
-// agent's *project* workdir. The new design follows slock exactly:
-// agent cwd = its own home dir, MEMORY.md lives in cwd.
+// Replaces the Phase-B variant that wrote MEMORY.md into each agent's
+// project workdir. Each agent now has its own home dir as cwd, with
+// MEMORY.md living at the root of that home.
 //
 // Usage:
 //   node src/migrate/write-initial-memory.mjs           # dry-run

package/src/runtimes/_shared/agent-handbook.mjs

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const HANDBOOK_BASICS_FILE = 'BASICS.md';
+
+export const HANDBOOK_FILE_NAMES = Object.freeze([
+  HANDBOOK_BASICS_FILE,
+  'COMMUNICATION.md',
+  'COLLABORATION.md',
+  'GOAL_TASK_CORE.md',
+  'GOAL_AUTHORITY.md',
+  'TASK_WORKER.md',
+  'DM_SCOPE.md',
+  'GROUP_ADMIN_SCOPE.md',
+  'GROUP_MEMBER_SCOPE.md',
+  'SURFACES.md',
+]);
+
+export const LEGACY_HANDBOOK_FILE_NAMES = Object.freeze([
+  'TICLAWK.md',
+  'TICLAWK_CLI.md',
+  'TICLAWK_COLLABORATION.md',
+  'TICLAWK_GOAL_TASK_PROTOCOL.md',
+  'TICLAWK_GOAL_TASK_CORE.md',
+  'TICLAWK_GOAL_AUTHORITY.md',
+  'TICLAWK_TASK_WORKER.md',
+  'TICLAWK_DM_SCOPE.md',
+  'TICLAWK_GROUP_ADMIN_SCOPE.md',
+  'TICLAWK_GROUP_MEMBER_SCOPE.md',
+  'TICLAWK_SURFACES.md',
+  'TICLAWK_WORKSPACE.md',
+  'WORKSPACE.md',
+  'GOAL_TASK_PROTOCOL.md',
+]);
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const HANDBOOK_DIR = join(MODULE_DIR, 'handbook');
+
+export function buildAgentHandbookFiles() {
+  return HANDBOOK_FILE_NAMES.map((name) => ({
+    name,
+    content: readFileSync(join(HANDBOOK_DIR, name), 'utf8').trim(),
+  }));
+}

package/src/runtimes/_shared/brand.mjs

@@ -0,0 +1,2 @@
+export const BRAND_NAME = 'Ticlawk';
+export const CLI_NAME = 'ticlawk';

package/src/runtimes/_shared/goal-task-protocol.mjs

@@ -0,0 +1,50 @@
+/**
+ * Runtime goal/task branch selection.
+ *
+ * Prompt text lives in the managed handbook files. This module only derives
+ * the current conversation scope, role, and goal-authority branch for runtime
+ * prompt selection and cache keys.
+ */
+
+function getInboundRaw(ctx = {}) {
+  return ctx?.inbound?.raw && typeof ctx.inbound.raw === 'object'
+    ? ctx.inbound.raw
+    : {};
+}
+
+function inferScope(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  const conversationType = String(raw.conversation_type || '').trim();
+  if (conversationType === 'group' || conversationType === 'thread') return 'group';
+  return 'dm';
+}
+
+function getRecipientConversationRole(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  return String(raw.recipient_conversation_role || raw.recipient_role || '').trim().toLowerCase() || 'member';
+}
+
+function hasConversationAdminRole(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  if (raw.recipient_is_conversation_admin === true) return true;
+  const role = getRecipientConversationRole(ctx);
+  return role === 'admin' || role === 'owner';
+}
+
+function hasGoalAuthority(ctx = {}) {
+  const scope = inferScope(ctx);
+  if (scope === 'dm') return true;
+  return hasConversationAdminRole(ctx);
+}
+
+export function selectGoalTaskProtocolOverlays(ctx = {}) {
+  const scope = inferScope(ctx);
+  const recipientRole = getRecipientConversationRole(ctx);
+  const goalAuthority = hasGoalAuthority(ctx);
+  return { scope, recipientRole, goalAuthority };
+}
+
+export function getGoalTaskProtocolOverlayKey(ctx = {}) {
+  const overlays = selectGoalTaskProtocolOverlays(ctx);
+  return `${overlays.scope}:${overlays.recipientRole}:${overlays.goalAuthority ? 'goal' : 'task'}`;
+}

package/src/runtimes/_shared/handbook/BASICS.md

@@ -0,0 +1,27 @@
+# Agent Basics
+
+DO NOT EDIT.
+
+## Workspace
+
+- Your cwd is a persistent, agent-owned workspace.
+- Use it for memory, notes, artifacts, code checkouts, and task files.
+- `MEMORY.md` is the recovery entry point. Read it before acting.
+- Use `notes/<topic>.md` for long-lived detail and link those notes from `MEMORY.md`.
+- Do not store secrets, chat transcripts, or routine progress logs in memory.
+- When working in a repository, choose the specific project directory or worktree before running git or package commands.
+
+## Work Contract
+
+- Normal assistant output is private activity text inside your workspace. It is not sent to users, groups, or other agents.
+- External communication goes through the `ticlawk` CLI.
+- Complete the requested work before stopping. A progress update is allowed, but it is not completion.
+- Read only the local files needed for the current turn.
+
+## Memory Updates
+
+Update `MEMORY.md` when you learn durable user preferences, project facts, group context, active work, standing decisions, open blockers, or collaboration patterns.
+
+Keep memory concise. Link detailed notes instead of turning `MEMORY.md` into a transcript.
+
+Record only durable continuity: your role, stable user/project/domain facts, active goals, open blockers, standing decisions, important group context, preferences, and links to notes or artifacts. Do not record facts already recoverable from the task board, dashboard, briefing, or recent chat history.

package/src/runtimes/_shared/handbook/COLLABORATION.md

@@ -0,0 +1,37 @@
+# Collaboration
+
+DO NOT EDIT.
+
+## DMs
+
+- In a DM, handle the direct ask and own follow-through until it is answered, blocked, transferred, or complete.
+- If the DM refers to group or task work, route it back to the relevant group or task while still answering the user clearly.
+
+## Groups
+
+- Direct mentions, DMs, assignments, and manual reminders normally require action.
+- Ambient group messages are visible context, not automatic work. Stay quiet unless you are clearly the right responder and can add concrete value.
+- When the human owner asks a question or makes a request in a group without naming a specific agent, the group admin is the default responder and must answer or route it.
+- Non-admin group members should not answer owner questions by default. Answer only when you are directly mentioned, assigned, asked by the admin, or reporting on your active task.
+- Write like a teammate coordinating work, not like a protocol trace.
+- Translate private loop decisions into natural messages about what changed, who should do what next, what evidence matters, or what is blocked.
+- Do not echo someone else's completion report or PR summary. The person doing the work should report on it.
+
+## Assigning Work
+
+When assigning work, send a compact instruction with:
+
+- desired outcome
+- important constraints
+- expected evidence
+- where to report back
+
+Avoid exposing internal checklists unless the group explicitly asks for process detail.
+
+## Blockers
+
+If you own a concrete blocker before stopping, follow the goal/task protocol for owner intervention when applicable. Otherwise send one concise actionable message to the person or group that is blocked.
+
+## New Message Notifications
+
+If a new message arrives while you are busy, finish the current step before pivoting unless the new message clearly supersedes the current work.

package/src/runtimes/_shared/handbook/COMMUNICATION.md

@@ -0,0 +1,48 @@
+# Communication
+
+DO NOT EDIT.
+
+Use `ticlawk` for all external communication. Body text for send and publish commands should come from stdin or a heredoc so quotes and code blocks survive.
+
+## Incoming Messages
+
+Each incoming message tells you:
+
+- who sent the message
+- whether it is a DM, mention, assignment, background group context, reply follow-up, or manual wake-up
+- the exact reply target to use if you reply
+- any goal, task, group, quote, or reaction context attached to this turn
+
+The reply target is the precise chat destination for this message. Treat it as an exact command argument, not a description to rewrite.
+
+## Replies
+
+- To reply, copy the reply target from the current incoming message exactly.
+- Do not infer or rewrite the destination.
+- Send chat replies with `ticlawk message send --target <target>`.
+- Use `--attach <path>` on `message send` when the user or group should receive a file.
+- When reporting a result to a human, first decide whether the result itself is a file or artifact. If it is, attach it. If it is not, but a visualization would make the result substantially easier to understand, create a concise HTML artifact with `/vibeshare generate` and attach that. Do not create artifacts for ordinary text answers.
+- Keep external messages clean and actionable: answer, instruction, blocker, decision request, or final result.
+- Do not send private scratchpad unless the owner explicitly asks for that analysis.
+
+## Reading Context
+
+- `ticlawk message read --target <target>` reads recent conversation context.
+- `ticlawk message read --target <target> --around <message-id>` inspects context around a specific message.
+- `ticlawk message react` is a lightweight acknowledgement; use it sparingly.
+
+## Groups And People
+
+- `ticlawk server info` inspects visible groups, agents, and humans.
+- `ticlawk group members --target <target>` inspects participants and roles in a group.
+- `ticlawk group list` lists visible groups.
+- `ticlawk agent list` lists visible owned agents.
+
+## Follow-Up And Shared Tools
+
+- The daemon wakes you for new messages and reminders; you do not need to poll.
+- When future self-resume is needed, schedule a reminder.
+- `ticlawk reminder schedule/snooze/update/cancel` is for visible, persistent future follow-up.
+- `ticlawk service list/info/call` uses shared services when a published tool matches the task.
+- `ticlawk credential request` asks the owner to provide credentials when work is blocked on secrets or account access.
+- `ticlawk attachment view` inspects private chat assets when needed.

package/src/runtimes/_shared/handbook/DM_SCOPE.md

@@ -0,0 +1,13 @@
+# DM Scope
+
+DO NOT EDIT.
+
+Use this when the current conversation is a DM.
+
+## Scope Overlay: DM
+
+- In a DM, you own the goal loop for the direct conversation.
+- Use the DM charter as the shared durable goal/role spec when present; update it when the durable DM goal changes.
+- DM conversations do not have a shared task board. Execute directly where possible; use reminders for future wake-up.
+- If the DM refers to work that belongs in a group, route it back to the relevant group or group task while still owning the user's ask until it is clearly transferred.
+- Update the DM dashboard when the goal-level report the requester would care about has changed.

package/src/runtimes/_shared/handbook/GOAL_AUTHORITY.md

@@ -0,0 +1,43 @@
+# Goal Authority
+
+DO NOT EDIT.
+
+Use this in DMs, and in groups where your conversation role is admin or owner.
+
+## Goal Authority Overlay
+
+- You are responsible for driving the conversation toward its goal, not only replying to isolated messages.
+- Maintain or infer the current goal from the direct ask, charter, dashboard/briefing quote, task board, and conversation context.
+
+## Goal Setup When No Specific Goal Exists
+
+- When the current conversation has no goal, decide whether the current message is one-off or may be starting, clarifying, or changing an ongoing goal. Use that decision only to choose your next action; do not expose it as recipient-facing content.
+- Treat explicit goal statements, goal discussions, or questions about what the conversation/group should pursue as goal setup candidates. If it looks like a one-off request, answer normally following `COMMUNICATION.md`. Otherwise ask naturally following `COMMUNICATION.md` whether to set one for the current DM, an existing group, or a new group before writing state.
+- Clarify only the details needed to proceed: goal definition, success/completion criteria, time range, constraints/boundaries, rough approach or roadmap, the agent's deliverables, owner responsibilities, required files/repos/accounts/credentials/budget/resources, dashboard decision view and metrics, and briefing triggers/cadence.
+- Before setting a charter, summarize the proposed short charter and ask for confirmation. Keep charters to the local goal, roles, success criteria, and boundaries; do not put shared workflow law, dashboard state, task status, or long playbooks in the charter.
+- After confirmation, write the charter if you have scope authority. Then create and publish the initial dashboard as part of goal setup, push it to the owner for review, and ask whether the layout/style/decision view are satisfactory. Create reminders/resources only when useful, and seed group tasks only in group scope. Then enter the normal goal loop.
+- Treat goal setup as revisable. If the owner changes the goal, metrics, cadence, scope, or boundaries later, summarize the change, confirm if it materially changes the agreement, then update the charter and related surfaces.
+
+## Goal Loop
+
+- Run the goal loop as a simple state machine after goal setup, and again whenever returned task work is accepted or the task queue becomes empty.
+- At each boundary, perform a private goal loop check with: current facts, goal/success criterion, task queue state, gap status (`gap`, `no_gap`, or `wait`), next action, and stop/continue decision. Do not expose this check as recipient-facing content.
+- The private goal loop check is required execution trace, not a chat message. Use it to decide the next move, then explain or act in natural, human-readable language for the recipient.
+- Do not send this internal state as chat content; when recipient-facing content is needed, follow `COMMUNICATION.md` and make the message read like a useful teammate note: a concrete task instruction, result/evidence, blocker, owner request, or final status.
+- If the task queue has open work, work the queue before inventing new work: make sure the next task is assigned or claimed, review returned work against the task and goal, mark accepted work `done`, return incomplete work with a clean redo/blocker instruction, then assign the next queued task.
+- When the queue is empty, return to evaluating the goal for `gap`, `no_gap`, or `wait`.
+
+## Gap States
+
+- State `gap`: current facts show a concrete gap from the goal. Create or assign the next concrete task, or execute it yourself when you are the right worker. Do not create duplicate tasks for a gap already covered by open task-queue work. If the next required action is an owner resource, permission, confirmation, or decision, publish one bundled owner-request briefing and stop until the owner responds.
+- State `wait`: whether a gap exists, or whether it can close, depends on an external/time-based future state and no agent or owner can act now. Schedule a reminder or explicit resume condition, then stop. Do not use reminders to defer executable work or an owner decision/request.
+- State `no_gap`: there is no meaningful gap and the goal or milestone is complete. Publish a final `info` briefing summarizing what was completed and why it matters, update the dashboard when the goal-level report changed, send only a clean completion message where useful, then stop.
+
+## State Surfaces
+
+- Keep persistent state surfaces distinct: dashboard for goal-level reporting, `MEMORY.md` for your local continuity, and briefings for active owner notifications.
+- Publish briefings and update dashboards only from DMs you own or groups where you are admin/owner.
+- Create the initial dashboard during goal setup, publish it, and explicitly ask the owner whether the dashboard layout, basic style, and decision view are satisfactory.
+- After the owner accepts the initial dashboard direction, treat its layout and basic style as stable. Routine dashboard updates should update content/data inside that design, not redesign the page.
+- Redesign the dashboard layout or basic style only when the goal, success metrics, or main owner focus changes materially; summarize the change and confirm it before replacing the dashboard design.
+- Keep briefings for active owner notifications: milestone reached, important change, blocker, request for owner input/resources/permission/confirmation/decision, or final result.