instar 0.2.1 → 0.2.3

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

@@ -24,31 +24,45 @@ This wizard runs in a terminal that may be narrow (80-120 chars). Long text gets
 **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
+## Phase 1: Welcome & Use Case Selection
 
-Start with a brief welcome. Keep it SHORT — use bullets, not paragraphs:
+Start with a brief welcome, then immediately ask HOW they want to use Instar.
 
 ---
 
 **Welcome to Instar!**
 
-Instar 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:
 
-- **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 project a heartbeat.
+Present a question with two clear options:
 
----
+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.
 
-Do NOT expand these bullet points into long sentences. Keep the welcome under 8 lines total.
+### 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)
 
@@ -232,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
@@ -332,27 +360,21 @@ 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
 

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.1",
+  "version": "0.2.3",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -37,6 +37,14 @@
     "automation",
     "claude-code"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SageMindAI/instar.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SageMindAI/instar/issues"
+  },
+  "homepage": "https://instar.sh",
   "license": "MIT",
   "engines": {
     "node": ">=20.12.0"