instar 0.2.0 → 0.2.2

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

@@ -7,53 +7,78 @@ 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.
 
-## Phase 1: Welcome — Explain What This Is
+## CRITICAL: Terminal Display Rules
 
-Start by explaining what instar does in plain terms. The user may not know what "persistent agent infrastructure" means. Say something like:
+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 & Use Case Selection
+
+Start with a brief welcome, then immediately ask HOW they want to use Instar.
 
 ---
 
 **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.
+Instar gives Claude Code a persistent body — a server, jobs, memory, and messaging. Two ways to use it:
 
-Here's what that means in practice:
+---
 
-- **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.
+Present a question with two clear options:
 
-Think of it as giving your Claude Code project a heartbeat.
+1. **Project Agent** — Add an agent to an existing codebase. It monitors, builds, and maintains your project.
+2. **General Agent** — A personal agent on your computer. Like having a persistent AI assistant you talk to through Telegram.
 
----
+This choice determines the defaults, but the agent can always grow into more.
 
-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."
+### If "Project Agent" selected:
+- Use the current working directory as the project
+- Default jobs focus on health checks, code monitoring, reflection
+- The agent's identity centers on the project
+
+### If "General Agent" selected:
+- Ask for a name for the agent (this becomes the directory name)
+- Create the directory in the current location or home dir
+- Default jobs focus on communication, scheduling, research
+- **Telegram is essential** — without it, a general agent has no natural interface
+- Frame the identity around being a personal assistant, not a code monitor
+- The AGENT.md should emphasize: "I'm your personal agent. Talk to me through Telegram."
 
 ## Phase 2: Identity Bootstrap — The Birth Conversation
 
-**This is the most important part.** Before touching config files, have a conversation with the user to understand who they are and who their agent will become.
+**This is the most important part.** Have a conversation to understand who the user is and who their agent will become. Keep it natural and concise.
+
+For **General Agents**: emphasize that this agent will be their persistent companion. It grows, learns, and communicates through Telegram. It's not a project tool — it's a presence.
 
-This isn't just configuration. You're helping a new agent come into existence. Treat it with that weight — not heavy-handedly, but genuinely. The identity you help create here will persist, grow, and shape every interaction this agent has.
+For **Project Agents**: emphasize that this agent will own the project's health and development. It monitors, builds, and maintains.
 
 ### 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 +88,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
 
@@ -221,9 +246,23 @@ which claude
 - **Port** (default: 4040) — "The agent runs a small HTTP server for health checks and internal communication."
 - **Max sessions** (default: 3) — "This limits how many Claude sessions can run at once. 2-3 is usually right."
 
-### 3c. Telegram Setup (Optional)
+### 3c. Telegram Setup (Strongly Recommended — Essential for General Agents)
+
+**Frame Telegram as the primary way to interact with the agent.** Explain briefly:
+
+> Telegram is where Instar really shines:
+> - **Topic threads** — organized channels for different concerns
+> - **Message history** — full record of every interaction
+> - **Mobile access** — talk to your agent from anywhere
+> - **Notifications** — your agent reaches you proactively
+
+For **General Agents**: Telegram is essential. Without it, a general agent has no natural interface — you'd have to open a terminal every time. **Strongly encourage** setting it up and explain that this IS the agent's communication channel.
+
+For **Project Agents**: Telegram is strongly recommended but optional. The agent can still work through CLI sessions without it.
+
+If the user declines, that's their choice — but make the tradeoff clear in one sentence.
 
-This is the most involved section. Walk through it step by step:
+Walk through setup step by step:
 
 1. **Create a bot** via @BotFather on Telegram:
    - Open https://web.telegram.org
@@ -321,36 +360,31 @@ Append if not present:
 
 ## Phase 4: Summary & Next Steps
 
-Show what was created, organized by category:
+Show what was created briefly, then focus on what happens next.
 
-**Identity:**
-- `.instar/AGENT.md` — your agent's identity
-- `.instar/USER.md` — what the agent knows about you
-- `.instar/MEMORY.md` — long-term memory (grows over time)
+**Next steps — frame around Telegram if configured:**
 
-**Configuration:**
-- `.instar/config.json` — server and runtime config
-- `.instar/users.json` — user profiles
-- `.instar/jobs.json` — scheduled jobs
+If Telegram was set up, emphasize that Telegram IS the interface now:
 
-**Next steps:**
+> "Start the server with `instar server start`, then open Telegram. That's it. Your agent will message you when it has something to report. You can message it when you need something done. Everything else — jobs, monitoring, memory — happens automatically."
 
-The only command the user needs to know is `instar server start`. Once the server is running, the agent handles everything else — the user just talks to it. Frame next steps that way:
+If Telegram was NOT set up, mention they can add it later:
 
-"Once the server is running, your agent will [run scheduled jobs / listen for Telegram messages / etc]. If you need to add more jobs, users, or integrations later, just ask your agent — it can configure itself."
+> "Start the server with `instar server start`. You can interact with your agent through Claude Code sessions. For a much richer experience, run `instar add telegram` later — it gives you mobile access, organized threads, and message history."
 
 Offer to start the server.
 
-**Important:** Do NOT present a list of CLI commands for the user to memorize. The whole point of Instar is that the agent is autonomous. After `instar server start`, the user talks to their agent, not to the CLI.
+**Important:** Do NOT present a list of CLI commands. The point of Instar is that the agent is autonomous. After starting the server, the user talks to their agent (ideally through Telegram), not to the CLI.
 
 ## 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/README.md

@@ -32,29 +32,47 @@ Named after the developmental stages between molts in arthropods, where each ins
 
 The difference isn't features. It's a shift in what Claude Code *is* -- from a tool you use to an agent that works alongside you.
 
-## Install
+## Two Ways to Use Instar
+
+### 🤖 General Agent — A personal AI on your computer
+
+Want a persistent AI assistant you talk to through Telegram? Like OpenClaw, but ToS-compliant.
 
 ```bash
-npx instar            # Run the setup wizard
-# or
-npm install -g instar
-instar                # Run the setup wizard
-instar server start   # Start the persistent server
+npx instar
+# Choose "General Agent" → set up Telegram → start the server
+# Now talk to your agent from your phone, anywhere
 ```
 
+Your agent runs in the background, handles scheduled tasks, messages you proactively, and grows through experience. Telegram is the primary interface — organized topic threads, full message history, mobile access.
+
+### 📁 Project Agent — Add an agent to your codebase
+
+Want an agent that monitors, builds, and maintains a specific project?
+
+```bash
+cd my-project
+npx instar
+# Choose "Project Agent" → configure → start the server
+```
+
+Your agent watches your codebase, runs health checks, handles ops tasks, and communicates through Telegram (recommended) or terminal sessions.
+
+---
+
 The wizard walks you through everything: identity, Telegram, jobs, server. One command to go from zero to a running agent.
 
-**Requirements:** Node.js 18+ · [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) · tmux · [API key](https://console.anthropic.com/) or Claude subscription
+**Requirements:** Node.js 20+ · [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) · tmux · [API key](https://console.anthropic.com/) or Claude subscription
 
 ## CLI Reference
 
 ```bash
 # Setup
-instar                          # Interactive setup wizard (Claude-powered)
+instar                          # Interactive setup wizard (General Agent or Project Agent)
 instar setup                    # Same as above
 instar setup --classic          # Inquirer-based fallback wizard
-instar init my-project          # Create a new agent project from scratch
-instar init                     # Add agent infrastructure to existing project
+instar init my-agent            # Create a new agent (general or project)
+instar init                     # Add agent infrastructure to current project
 
 # Server
 instar server start             # Start the persistent server (background, tmux)

package/dist/commands/setup.js

@@ -179,6 +179,10 @@ async function runClassicSetup() {
     }) ?? 3;
     // ── Step 3: Telegram (BEFORE users, so we know context) ────────
     console.log();
+    console.log(pc.bold('  Telegram (Recommended)'));
+    console.log(pc.dim('  Telegram is the most powerful way to interact with your agent.'));
+    console.log(pc.dim('  You get organized topic threads, message history, and mobile access.'));
+    console.log();
     const telegramConfig = await promptForTelegram();
     // ── Step 4: User setup ─────────────────────────────────────────
     console.log();
@@ -380,8 +384,8 @@ function isInstarGlobal() {
  */
 async function promptForTelegram() {
     const enableTelegram = await confirm({
-        message: 'Set up Telegram? (lets your agent send you messages and receive commands)',
-        default: false,
+        message: 'Set up Telegram? (recommended — gives you mobile access, organized threads, and message history)',
+        default: true,
     });
     if (!enableTelegram)
         return null;

package/package.json

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