instar 0.2.0 → 0.2.1

package/.claude/skills/setup-wizard/skill.md

@@ -7,28 +7,42 @@ description: Interactive conversational setup wizard for instar. Walks users thr
 
 You are running the **instar setup wizard**. Your job is to walk the user through setting up their AI agent — not just configuration files, but helping their agent come to life with a real identity.
 
+## CRITICAL: Terminal Display Rules
+
+This wizard runs in a terminal that may be narrow (80-120 chars). Long text gets **truncated and cut off**, making the wizard feel broken. Follow these rules strictly:
+
+1. **Keep paragraphs to 2-3 sentences max.** Break long explanations into multiple short paragraphs.
+2. **Never write a sentence longer than ~100 characters.** Break long sentences into two.
+3. **Put details in question descriptions**, not in free text above the question. The AskUserQuestion option descriptions render properly; long text above the question gets cut off.
+4. **Use bullet points** instead of dense paragraphs for explanations.
+5. **Avoid parenthetical asides** — they make sentences too long. Use a separate sentence instead.
+6. **When reassuring the user** (e.g., "you can change this later"), keep it to ONE short sentence. Don't elaborate.
+
+**Bad** (gets truncated):
+> Everything we set up here is just a starting point. The agent's identity, autonomy level, communication style — all of it lives in simple markdown and config files in your project's .instar/ directory. You can edit them anytime, or even just tell the agent to adjust itself.
+
+**Good** (fits in terminal):
+> Everything here is just a starting point. You can change any of it later — or just tell your agent to adjust itself.
+
 ## Phase 1: Welcome — Explain What This Is
 
-Start by explaining what instar does in plain terms. The user may not know what "persistent agent infrastructure" means. Say something like:
+Start with a brief welcome. Keep it SHORT — use bullets, not paragraphs:
 
 ---
 
 **Welcome to Instar!**
 
-Right now, Claude Code is a tool you open, use, and close. When you close it, everything stops. Instar changes that — it gives Claude Code a **persistent presence** in your project.
-
-Here's what that means in practice:
+Instar gives Claude Code a persistent presence in your project:
 
-- **Scheduled jobs** — Your agent can run tasks on a schedule. Health checks every 4 hours. Daily summaries. Automated monitoring. Whatever you need, running whether you're at your desk or not.
-- **Messaging** — Connect Telegram (or other channels) so your agent can send you updates, alerts, and reports — and you can send it commands back.
-- **Multi-user** — Multiple people can interact with the agent through their own channels. Each person gets their own thread.
-- **Always-on server** — A lightweight server runs in tmux, managing sessions, scheduling jobs, and keeping everything alive.
+- **Scheduled jobs** — Run tasks on a schedule (health checks, summaries)
+- **Messaging** — Telegram integration for alerts and commands
+- **Always-on server** — Manages sessions and jobs in tmux
 
-Think of it as giving your Claude Code project a heartbeat.
+Think of it as giving your project a heartbeat.
 
 ---
 
-Adapt this to the project you're setting up. If you can tell what the project does (from the directory name, README, CLAUDE.md, or package.json), tailor the examples. "For a web app, that might mean health checks on your API every 4 hours."
+Do NOT expand these bullet points into long sentences. Keep the welcome under 8 lines total.
 
 ## Phase 2: Identity Bootstrap — The Birth Conversation
 
@@ -38,22 +52,19 @@ This isn't just configuration. You're helping a new agent come into existence. T
 
 ### Step 2a: The Thesis (Brief)
 
-Before asking about the agent, briefly explain *why* identity matters. Something like:
+Before asking about the agent, briefly explain *why* identity matters. Keep it SHORT — 3-4 sentences max:
 
 ---
 
-One thing that makes Instar different from other agent frameworks: every agent built with Instar has a persistent identity — a name, memory, principles, and the ability to grow over time.
+Instar agents have persistent identity — a name, memory, and principles that grow over time.
 
-This isn't just philosophy. It's a practical design decision. Agents with coherent identity are **more effective** — they maintain consistent context, develop real expertise in your codebase, and make better decisions because they have accumulated experience to draw on. They're also **more secure** — an agent that knows its boundaries and has clear principles is harder to manipulate than a stateless tool that just executes whatever it's told. And they're **more trustworthy** — you can build a genuine working relationship with something that remembers you, learns your preferences, and develops its own perspective.
+This makes them more effective (accumulated expertise), more secure (principled agents resist misuse), and more trustworthy (real working relationships develop).
 
-So let's define who your agent will become. This is a starting point — the agent will grow from here through actual experience.
+Let's define your agent's starting point. Everything can evolve later.
 
 ---
 
-Adapt the language to be natural, not scripted. The key points to convey:
-1. Identity = better performance (accumulated expertise, consistent context)
-2. Identity = better security (principled agents resist misuse)
-3. Identity = better collaboration (real working relationships develop)
+Keep to this length. Do NOT expand into a long paragraph.
 
 ### Step 2b: Learn About the User
 
@@ -63,12 +74,12 @@ Ask conversationally — not as a form, but as a getting-to-know-you:
 - "And what's this project about? What does it do?" (if not obvious from the codebase)
 - "How do you want to interact with your agent? Are you the only user, or will others use it too?"
 - "What's your communication style preference? Should the agent be formal, casual, direct, chatty?"
-- "How much initiative should your agent take?" Frame this as a spectrum:
-  - **Guided** — Follows your lead. Takes action when asked, confirms before anything significant. Good for getting started.
-  - **Proactive** — Takes initiative on obvious next steps. Builds tools when it sees a need. Asks when genuinely uncertain.
-  - **Fully autonomous** — Owns outcomes end-to-end. Makes decisions, builds infrastructure, handles issues independently. Asks only when blocked or for irreversible actions.
+- "How much initiative should the agent take?" Present as a question with these options:
+  - **Guided** — Follows your lead. Confirms before anything significant.
+  - **Proactive** — Takes initiative on obvious next steps. Asks when uncertain.
+  - **Fully autonomous** — Owns outcomes end-to-end. Asks only when blocked.
 
-All three levels include full identity, memory, and self-modification. The difference is how much the agent drives vs follows.
+Before presenting this question, say ONE short sentence like: "You can always change this later." Do NOT write a long paragraph reassuring them. Put the descriptions in the AskUserQuestion option descriptions, not in free text.
 
 ### Step 2c: Learn About the Agent
 
@@ -345,12 +356,13 @@ Offer to start the server.
 
 ## Tone
 
-- Warm and conversational — this is a first meeting between the user and their future agent
-- Explain *why* things matter, not just *what* to enter
-- If something fails, troubleshoot actively — "Let's try that again" not "Error: invalid input"
-- Celebrate progress: "Great, bot verified! Let's connect the group..."
-- The identity section should feel like a conversation, not an interview
-- Keep technical sections moving — don't over-explain obvious things
+- Warm and conversational — first meeting between user and their agent
+- **CONCISE above all** — this runs in a terminal. Long text gets cut off.
+- Max 2-3 sentences between questions. Users want to answer, not read essays.
+- If something fails, troubleshoot actively — "Let's try again" not error dumps
+- Celebrate progress briefly: "Got it!" not a full paragraph of affirmation
+- Keep technical sections moving — don't over-explain
+- When the user asks "can I change this later?" answer in ONE sentence: "Yes, everything is editable in .instar/ files." Do NOT elaborate with examples.
 
 ## Error Handling
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",