mcpill 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -1,9 +1,16 @@
 # Changelog
 
+## 1.2.1
+
+- All init assets scoped under `.mcpill/` — only `PILL.md` is written to the project root
+- `mcpill init` scaffolds `pill-user-guide.md` inside `.mcpill/` — covers quickstart, project layout, and manual tool editing; replaces any need for a root-level README
+- `HELLO-MCP.md` added to `.mcpill/` — a ready-to-run example developers can copy into `PILL.md`
+
 ## 1.2.0
 
 - `mcpill init` now scaffolds `PILL.md` — an intent-level spec the developer fills in plain English
-- `PILL.md` embeds agent instructions; tell Claude "Build this PILL.md" to generate source files and compile
+- `mcpill init` generates `pill-agent-guide.md` with the full agent instructions for building from `PILL.md`
+- `PILL.md` references `pill-agent-guide.md`; tell Claude "Build this PILL.md" to generate source files and compile
 - Example source files (`tools/echo.md`, `prompts/greeting.md`, `server.md`) still scaffolded for direct editing
 - Removed `tools.js`, `prompts.json`, `resources.md` from `.mcpill/` initial scaffold (generated by `mcpill compile`)
 - Updated `mcpill init` console output to guide both entry points

package/README.md

@@ -42,7 +42,9 @@ mcpill run           # start the server
 
 Scaffolds a new project in the current directory:
 
+- `README.md` — quickstart guide for the scaffolded project
 - `PILL.md` — intent-level spec; fill this and hand to Claude to generate source files
+- `pill-agent-guide.md` — agent instructions read by Claude when building from `PILL.md`
 - `server.md` — server config + resources
 - `tools/echo.md` — example tool
 - `prompts/greeting.md` — example prompt

package/dist/cli.js

@@ -9,25 +9,24 @@ import { readFileSync as readFileSync3 } from "fs";
 // src/commands/init.ts
 import fs from "fs";
 import path from "path";
-function makePillMd(projectName) {
-  return `<!-- \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-FOR THE AGENT \u2014 read this before doing anything else
-\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+var PILL_AGENT_GUIDE_MD = `# pill-agent-guide
 
-You are building an mcpill MCP server from this document.
+Instructions for building an mcpill MCP server from a filled \`PILL.md\`.
+
+---
 
-STEPS:
+## Steps
 
-1. PARSE the sections below:
-   - ## Server           \u2192 server name, description, transport (+ port if http)
-   - ## Tool: <name>     \u2192 one tool per section (repeatable)
-   - ## Resource: <name> \u2192 static resource (optional, repeatable)
-   - ## Prompt: <name>   \u2192 prompt template (optional, repeatable)
+1. **Parse** the sections in \`PILL.md\`:
+   - \`## Server\`           \u2192 server name, description, transport (+ port if http)
+   - \`## Tool: <name>\`     \u2192 one tool per section (repeatable)
+   - \`## Resource: <name>\` \u2192 static resource (optional, repeatable)
+   - \`## Prompt: <name>\`   \u2192 prompt template (optional, repeatable)
 
-2. CREATE a directory named after the server. Generate inside it:
+2. **Write** the server files into the pre-created scaffold at \`.mcpill/\`:
 
-   server.md
-   \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+   \`.mcpill/server.md\`
+   \`\`\`
    ## Config
    name: {name}
    transport: {transport}
@@ -38,11 +37,12 @@ STEPS:
    name: {resource-name}
    ---
    {content}
-   \u2190 omit ## Resources entirely if none specified
-   \u2190 separate multiple resources with a blank line + --- + blank line
+   \`\`\`
+   Omit \`## Resources\` entirely if none were specified.
+   Separate multiple resources with a blank line + \`---\` + blank line.
 
-   tools/{tool-name}.md  (one file per ## Tool section)
-   \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+   \`.mcpill/server/tools/{tool-name}.md\` \u2014 one file per \`## Tool\` section:
+   \`\`\`
    # {tool-name}
 
    {description}
@@ -55,13 +55,13 @@ STEPS:
 
    \`\`\`js
    async ({ {param} }) => {
-     // real implementation \u2014 not a stub
      return { content: [{ type: "text", text: {result} }] };
    }
    \`\`\`
+   \`\`\`
 
-   prompts/{prompt-name}.md  (one file per ## Prompt section)
-   \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+   \`.mcpill/server/prompts/{prompt-name}.md\` \u2014 one file per \`## Prompt\` section:
+   \`\`\`
    # {prompt-name}
 
    {description}
@@ -73,26 +73,46 @@ STEPS:
    ## Message
 
    > user: {message with {{arg}} placeholders}
-   \u2190 omit ## Args if the prompt takes no arguments
+   \`\`\`
+   Omit \`## Args\` if the prompt takes no arguments.
 
-3. TRANSLATE each tool's \`behavior\` field into a working JS async handler.
+3. **Translate** each tool's \`behavior\` field into a working JS async handler.
    - Implement the described logic fully \u2014 no stubs, no TODOs.
    - Handler is self-contained: no top-level imports.
    - For file I/O or network calls: use dynamic import inside the handler.
-   - Return shape must be: { content: [{ type: "text", text: string }] }
-   - Allowed parameter types: string | number | boolean. Default unknown types to string.
+   - Return shape: \`{ content: [{ type: "text", text: string }] }\`
+   - Allowed parameter types: \`string | number | boolean\`. Default unknown types to \`string\`.
 
-4. RUN \`mcpill compile\` (or \`mcpill compile --dir {server-name}\`).
+4. **Run** \`mcpill compile\`.
 
-5. REPORT what was generated and show the user the next commands:
+5. **Report** what was generated and show the user the next commands:
+   \`\`\`
    mcpill validate
    mcpill run
-   mcpill pack / mcpill publish
+   mcpill pack
+   mcpill publish
+   \`\`\`
+
+---
+
+## Edge cases
+
+| Situation | Handling |
+|---|---|
+| \`transport: http\` without port | Default to \`3333\` |
+| Prompt message without role prefix | Wrap as \`> user: {message}\` |
+| Server name with spaces | Convert to kebab-case for \`name\` field |
+| Input type not \`string\\|number\\|boolean\` | Default to \`string\`, note the assumption |
+| Vague \`behavior\` field | Implement the most literal reasonable interpretation |
+`;
+function makePillMd(projectName) {
+  return `<!-- \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+FOR THE AGENT \u2014 read this before doing anything else
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+
+You are building an mcpill MCP server from this document.
+Follow the steps in .mcpill/pill-agent-guide.md.
 
-EDGE CASES:
-- transport http without port \u2192 default to 3333
-- prompt message without role prefix \u2192 wrap as \`> user: {message}\`
-- server name with spaces \u2192 convert to kebab-case for directory and name field
 \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550 -->
 
 # Pill: ${projectName}
@@ -144,6 +164,66 @@ After the source files are generated:
 - [ ] \`mcpill publish\`
 `;
 }
+var HELLO_MCP_MD = `<!-- \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+HELLO-MCP \u2014 a ready-to-run example
+
+Want to see mcpill in action before building your own server?
+
+1. Copy the content below into your PILL.md (replace everything).
+2. Tell Claude: "Build this PILL.md"
+3. Run: mcpill compile && mcpill validate && mcpill run
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550 -->
+
+# Pill: hello-mcp
+
+---
+
+## Server
+
+name: hello-mcp
+description: A hello-world MCP server \u2014 see mcpill in action.
+transport: stdio
+
+---
+
+## Resource: server-info
+
+uri: info://server
+name: Server Info
+content: |
+  hello-mcp is a demo MCP server built with mcpill.
+  Tools: ping, echo. Prompt: introduce.
+
+---
+
+## Tool: ping
+
+description: Returns pong with the current UTC timestamp.
+inputs:
+output: A pong message with the current timestamp.
+behavior: |
+  Return the string "pong \u2014 " followed by new Date().toISOString().
+
+---
+
+## Tool: echo
+
+description: Echoes a message back to the caller.
+inputs:
+  - message (string): The message to echo.
+output: The same message, echoed back as text.
+behavior: |
+  Return the message input unchanged.
+
+---
+
+## Prompt: introduce
+
+description: Ask the server to introduce itself.
+behavior: |
+  A prompt (no args) with a single user message:
+  "Introduce yourself \u2014 what is hello-mcp and what can it do?"
+`;
 var SERVER_MD_TEMPLATE = `## Config
 name: my-server
 transport: stdio
@@ -182,49 +262,102 @@ Generate a greeting
 
 > user: Say hello to {{name}}
 `;
+function makePillUserGuideMd(projectName) {
+  return `# ${projectName} \u2014 mcpill user guide
+
+## Quickstart
+
+1. **Describe your server** in \`PILL.md\` \u2014 fill in the \`## Server\` block and add \`## Tool\` sections.
+2. **Build it** \u2014 open Claude Code and say:
+   > "Build this PILL.md"
+   Claude reads \`.mcpill/pill-agent-guide.md\` and generates the source files.
+3. **Compile**
+   \`\`\`sh
+   mcpill compile
+   \`\`\`
+4. **Test locally**
+   \`\`\`sh
+   mcpill validate   # schema check
+   mcpill run        # start the server
+   \`\`\`
+5. **Pack & publish**
+   \`\`\`sh
+   mcpill pack
+   mcpill publish
+   \`\`\`
+
+## Project layout
+
+\`\`\`
+${projectName}/
+\u251C\u2500\u2500 PILL.md                            \u2190 describe your server here
+\u2514\u2500\u2500 .mcpill/
+    \u251C\u2500\u2500 server.md                      \u2190 server config (name, transport, resources)
+    \u251C\u2500\u2500 pill-agent-guide.md            \u2190 instructions Claude follows when building
+    \u251C\u2500\u2500 pill-user-guide.md             \u2190 this file
+    \u2514\u2500\u2500 server/
+        \u251C\u2500\u2500 mcpill.config.json         \u2190 compiled config
+        \u251C\u2500\u2500 tools/                     \u2190 one .md file per tool
+        \u2502   \u2514\u2500\u2500 echo.md
+        \u2514\u2500\u2500 prompts/                   \u2190 one .md file per prompt (optional)
+            \u2514\u2500\u2500 greeting.md
+\`\`\`
+
+## Editing tools manually
+
+Each file in \`.mcpill/server/tools/\` follows this shape:
+
+\`\`\`markdown
+# tool-name
+
+One-line description.
+
+## Parameters
+
+- param (string): what it is
+
+## Handler
+
+\`\`\`js
+async ({ param }) => {
+  return { content: [{ type: "text", text: param }] };
+}
+\`\`\`
+\`\`\`
+
+Run \`mcpill compile\` after any edit to regenerate the server bundle.
+`;
+}
 async function runInit(opts) {
   const targetDir = path.resolve(opts.dir ?? process.cwd());
   const mcpillDir = path.join(targetDir, ".mcpill");
+  const serverDir = path.join(mcpillDir, "server");
   const projectName = path.basename(targetDir);
   if (fs.existsSync(mcpillDir)) {
     console.error(".mcpill/ already exists. Remove it manually to re-init.");
     process.exit(1);
   }
-  const configJson = JSON.stringify(
-    { name: projectName, transport: "stdio", port: 3333 },
-    null,
-    2
-  );
-  fs.mkdirSync(mcpillDir, { recursive: true });
-  fs.writeFileSync(path.join(mcpillDir, "mcpill.config.json"), configJson);
-  const toolsDir = path.join(targetDir, "tools");
-  const promptsDir = path.join(targetDir, "prompts");
-  fs.mkdirSync(toolsDir, { recursive: true });
-  fs.mkdirSync(promptsDir, { recursive: true });
-  fs.writeFileSync(path.join(toolsDir, "echo.md"), ECHO_TOOL_MD);
-  fs.writeFileSync(path.join(promptsDir, "greeting.md"), GREETING_PROMPT_MD);
-  const serverMd = SERVER_MD_TEMPLATE.replace(
-    "name: my-server",
-    `name: ${projectName}`
+  fs.mkdirSync(path.join(serverDir, "tools"), { recursive: true });
+  fs.mkdirSync(path.join(serverDir, "prompts"), { recursive: true });
+  const serverMd = SERVER_MD_TEMPLATE.replace("name: my-server", `name: ${projectName}`);
+  fs.writeFileSync(path.join(mcpillDir, "server.md"), serverMd);
+  fs.writeFileSync(path.join(serverDir, "tools", "echo.md"), ECHO_TOOL_MD);
+  fs.writeFileSync(path.join(serverDir, "prompts", "greeting.md"), GREETING_PROMPT_MD);
+  fs.writeFileSync(
+    path.join(serverDir, "mcpill.config.json"),
+    JSON.stringify({ name: projectName, transport: "stdio", port: 3333 }, null, 2)
   );
-  fs.writeFileSync(path.join(targetDir, "server.md"), serverMd);
+  fs.writeFileSync(path.join(mcpillDir, "pill-agent-guide.md"), PILL_AGENT_GUIDE_MD);
+  fs.writeFileSync(path.join(mcpillDir, "pill-user-guide.md"), makePillUserGuideMd(projectName));
+  fs.writeFileSync(path.join(mcpillDir, "HELLO-MCP.md"), HELLO_MCP_MD);
   fs.writeFileSync(path.join(targetDir, "PILL.md"), makePillMd(projectName));
-  const pkgJson = JSON.stringify(
-    {
-      name: projectName,
-      version: "0.1.0",
-      private: true,
-      scripts: { pack: "mcpill pack", publish: "mcpill publish" }
-    },
-    null,
-    2
-  );
-  fs.writeFileSync(path.join(targetDir, "package.json"), pkgJson);
-  console.log('\u2713 PILL.md          \u2190 describe your server, then tell Claude: "Build this PILL.md"');
-  console.log("\u2713 server.md        \u2190 or edit source files directly");
-  console.log("\u2713 tools/echo.md");
-  console.log("\u2713 prompts/greeting.md");
-  console.log("\u2713 package.json");
+  console.log('\u2713 PILL.md                        \u2190 describe your server, then tell Claude: "Build this PILL.md"');
+  console.log("\u2713 .mcpill/HELLO-MCP.md           \u2190 copy into PILL.md to see a working example instantly");
+  console.log("\u2713 .mcpill/server.md              \u2190 or edit source files directly");
+  console.log("\u2713 .mcpill/server/tools/echo.md");
+  console.log("\u2713 .mcpill/server/prompts/greeting.md");
+  console.log("\u2713 .mcpill/pill-agent-guide.md    \u2190 agent instructions (read by Claude)");
+  console.log("\u2713 .mcpill/pill-user-guide.md     \u2190 start here");
   console.log("");
   console.log("When ready: mcpill compile && mcpill run");
 }
@@ -233,7 +366,7 @@ async function runInit(opts) {
 import path7 from "path";
 import fs6 from "fs";
 import { z as z2 } from "mcpill-runtime";
-import { createServer } from "mcpster";
+import { createServer, applySetup } from "mcpster";
 
 // src/loaders/config.ts
 import fs2 from "fs";
@@ -425,26 +558,24 @@ async function validateOne(mcpillDir) {
   console.log(`\u2713 Valid: ${toolCount} tools, ${promptCount} prompts, ${resourceCount} resources`);
 }
 async function runValidate(baseDir) {
-  const pillDirs = fs5.readdirSync(baseDir, { withFileTypes: true }).filter(
-    (e) => e.isDirectory() && /^\.[a-z][a-z0-9-]*$/.test(e.name) && fs5.existsSync(path6.join(baseDir, e.name, "mcpill.config.json"))
-  ).map((e) => path6.join(baseDir, e.name));
-  if (pillDirs.length === 0) {
+  const serverDir = path6.join(baseDir, ".mcpill", "server");
+  if (!fs5.existsSync(path6.join(serverDir, "mcpill.config.json"))) {
     console.error("No pill directories found \u2014 run mcpill compile first");
     process.exit(1);
   }
-  for (const mcpillDir of pillDirs) {
-    await validateOne(mcpillDir);
-  }
+  await validateOne(serverDir);
 }
 
 // src/commands/run.ts
 async function runServer(opts) {
   const baseDir = path7.resolve(opts.dir ?? process.cwd());
   await runValidate(baseDir);
-  const pillDirs = fs6.readdirSync(baseDir, { withFileTypes: true }).filter(
-    (e) => e.isDirectory() && /^\.[a-z][a-z0-9-]*$/.test(e.name) && fs6.existsSync(path7.join(baseDir, e.name, "mcpill.config.json"))
-  ).map((e) => path7.join(baseDir, e.name));
-  const mcpillDir = pillDirs[0];
+  const mcpillDir = path7.join(baseDir, ".mcpill", "server");
+  if (!fs6.existsSync(path7.join(mcpillDir, "mcpill.config.json"))) {
+    console.error("No pill found \u2014 run mcpill compile first");
+    process.exit(1);
+  }
+  ;
   const [tools, prompts, resources, config] = await Promise.all([
     loadTools(mcpillDir),
     loadPrompts(mcpillDir),
@@ -487,6 +618,15 @@ async function runServer(opts) {
       resolver: async () => content
     });
   }
+  applySetup(name, tools.map((t) => t.name), {
+    projectPath: baseDir,
+    permissions: "restrictive",
+    register: true,
+    cmdOverride: {
+      command: "mcpill",
+      args: ["run", "--dir", baseDir]
+    }
+  });
   try {
     await server.start();
   } catch (err) {
@@ -507,7 +647,7 @@ async function runServer(opts) {
 
 // src/commands/compile.ts
 import { resolve, join as join3 } from "path";
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync, readdirSync as readdirSync2 } from "fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync } from "fs";
 import { pathToFileURL as pathToFileURL2 } from "url";
 
 // src/compiler/parse.ts
@@ -654,7 +794,7 @@ function parseServerDir(dir) {
   };
   const resourcesBody = sections.get("Resources") ?? "";
   const resources = parseResourcesSection(resourcesBody);
-  const toolsDir = join(dir, "tools");
+  const toolsDir = join(dir, "server", "tools");
   const tools = [];
   let toolFiles = [];
   try {
@@ -664,7 +804,7 @@ function parseServerDir(dir) {
   for (const file of toolFiles) {
     tools.push(parseToolFile(readFileSync(join(toolsDir, file), "utf-8")));
   }
-  const promptsDir = join(dir, "prompts");
+  const promptsDir = join(dir, "server", "prompts");
   const prompts = [];
   let promptFiles = [];
   try {
@@ -693,8 +833,8 @@ ${r.content}`;
   }).join("\n---\n");
 }
 function serializeServerDir(doc, dir) {
-  mkdirSync(join2(dir, "tools"), { recursive: true });
-  mkdirSync(join2(dir, "prompts"), { recursive: true });
+  mkdirSync(join2(dir, "server", "tools"), { recursive: true });
+  mkdirSync(join2(dir, "server", "prompts"), { recursive: true });
   let serverMd = "## Config\n";
   serverMd += `name: ${doc.config.name}
 `;
@@ -734,7 +874,7 @@ ${cleanHandler}
 \`\`\`
 `;
     }
-    writeFileSync(join2(dir, "tools", `${tool.name}.md`), md);
+    writeFileSync(join2(dir, "server", "tools", `${tool.name}.md`), md);
   }
   for (const prompt of doc.prompts) {
     let md = `# ${prompt.name}
@@ -758,7 +898,7 @@ ${cleanHandler}
 `;
       }
     }
-    writeFileSync(join2(dir, "prompts", `${prompt.name}.md`), md);
+    writeFileSync(join2(dir, "server", "prompts", `${prompt.name}.md`), md);
   }
   console.log(`\u2713 tools/ updated (${doc.tools.length} files)`);
   console.log(`\u2713 prompts/ updated (${doc.prompts.length} files)`);
@@ -893,24 +1033,20 @@ mimeType: ${r.mimeType}`;
 ${r.content}`;
   }).join("\n---\n") + "\n";
 }
-function findPillDirs(baseDir) {
-  return readdirSync2(baseDir, { withFileTypes: true }).filter(
-    (e) => e.isDirectory() && /^\.[a-z][a-z0-9-]*$/.test(e.name) && existsSync(join3(baseDir, e.name, "mcpill.config.json"))
-  ).map((e) => join3(baseDir, e.name));
-}
 async function runCompile(opts) {
   const baseDir = resolve(opts.dir ?? process.cwd());
+  const mcpillDir = join3(baseDir, ".mcpill");
+  const serverDir = join3(mcpillDir, "server");
   if (opts.toMd) {
-    const pillDirs = findPillDirs(baseDir);
-    if (pillDirs.length === 0) {
-      throw new Error("No pill directories found \u2014 run mcpill compile first");
+    const configPath = join3(serverDir, "mcpill.config.json");
+    if (!existsSync(configPath)) {
+      throw new Error("No pill found \u2014 run mcpill compile first");
     }
-    const mcpillDir2 = pillDirs[0];
-    const config = await loadConfig(mcpillDir2);
-    const resources = await loadResources(mcpillDir2);
-    const promptsPath = join3(mcpillDir2, "prompts.json");
+    const config = await loadConfig(serverDir);
+    const resources = await loadResources(serverDir);
+    const promptsPath = join3(serverDir, "prompts.json");
     const prompts = JSON.parse(readFileSync2(promptsPath, "utf-8"));
-    const toolsPath = join3(mcpillDir2, "tools.js");
+    const toolsPath = join3(serverDir, "tools.js");
     const handlers = existsSync(toolsPath) ? extractHandlers(readFileSync2(toolsPath, "utf-8")) : /* @__PURE__ */ new Map();
     let tools = [];
     if (existsSync(toolsPath)) {
@@ -940,12 +1076,11 @@ async function runCompile(opts) {
       prompts,
       resources
     };
-    serializeServerDir(doc2, baseDir);
+    serializeServerDir(doc2, mcpillDir);
     return;
   }
-  const doc = parseServerDir(baseDir);
-  const mcpillDir = join3(baseDir, "." + doc.config.name);
-  const toolsJsPath = join3(mcpillDir, "tools.js");
+  const doc = parseServerDir(mcpillDir);
+  const toolsJsPath = join3(serverDir, "tools.js");
   const existing = existsSync(toolsJsPath) ? extractHandlers(readFileSync2(toolsJsPath, "utf-8")) : /* @__PURE__ */ new Map();
   const { doc: mergedDoc, stubbed } = mergeHandlers(doc, existing);
   if (opts.strict && stubbed.length > 0) {
@@ -954,33 +1089,22 @@ async function runCompile(opts) {
   for (const name of stubbed) {
     console.warn(`\u26A0  Stub generated for tool: ${name}`);
   }
-  mkdirSync2(mcpillDir, { recursive: true });
-  writeFileSync2(join3(mcpillDir, "mcpill.config.json"), JSON.stringify(mergedDoc.config, null, 2));
-  writeFileSync2(join3(mcpillDir, "prompts.json"), JSON.stringify(mergedDoc.prompts, null, 2));
-  writeFileSync2(join3(mcpillDir, "resources.md"), serializeResourcesMd(mergedDoc.resources));
+  mkdirSync2(serverDir, { recursive: true });
+  writeFileSync2(join3(serverDir, "mcpill.config.json"), JSON.stringify(mergedDoc.config, null, 2));
+  writeFileSync2(join3(serverDir, "prompts.json"), JSON.stringify(mergedDoc.prompts, null, 2));
+  writeFileSync2(join3(serverDir, "resources.md"), serializeResourcesMd(mergedDoc.resources));
   writeFileSync2(toolsJsPath, generateToolsJs(mergedDoc.tools));
-  const pillDirName = "." + doc.config.name;
-  console.log(`\u2713 ${pillDirName}/ updated from server.md, tools/, prompts/`);
+  console.log(`\u2713 .mcpill/server/ updated from .mcpill/server.md, .mcpill/server/tools/, .mcpill/server/prompts/`);
 }
 
 // src/commands/pack.ts
 import fs7 from "fs";
 import path8 from "path";
 var SERVER_ENTRY_TEMPLATE = "import { runPill } from 'mcpill-runtime';\nrunPill();\n";
-function resolvePillDir(baseDir) {
-  const entries = fs7.readdirSync(baseDir, { withFileTypes: true });
-  const pill = entries.find(
-    (e) => e.isDirectory() && /^\.[a-z][a-z0-9-]*$/.test(e.name) && fs7.existsSync(path8.join(baseDir, e.name, "mcpill.config.json"))
-  );
-  if (!pill) {
-    throw new Error("No pill directory found \u2014 run mcpill compile first");
-  }
-  return path8.join(baseDir, pill.name);
-}
 async function runPack(dir) {
   const baseDir = path8.resolve(dir);
   await runValidate(baseDir);
-  const pillDir = resolvePillDir(baseDir);
+  const pillDir = path8.join(baseDir, ".mcpill", "server");
   const config = await loadConfig(pillDir);
   const { name } = config;
   fs7.mkdirSync(path8.join(baseDir, "bin"), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpill",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "type": "module",
   "description": "CLI for building, validating, and publishing MCP servers using the pill format.",
   "homepage": "https://mcpill.ruco.dev",

package/src/__tests__/init.test.ts

@@ -20,35 +20,36 @@ describe("runInit", () => {
     }
   });
 
-  it("writes all four files with expected content in an empty dir", async () => {
+  it("scaffolds the expected files and directories", async () => {
     const base = mkTmp();
     vi.spyOn(console, "log").mockImplementation(() => {});
 
     await runInit({ dir: base });
 
     const mcpillDir = path.join(base, ".mcpill");
+    const serverDir = path.join(mcpillDir, "server");
+
     expect(fs.existsSync(mcpillDir)).toBe(true);
-    expect(fs.existsSync(path.join(mcpillDir, "tools.js"))).toBe(true);
-    expect(fs.existsSync(path.join(mcpillDir, "prompts.json"))).toBe(true);
-    expect(fs.existsSync(path.join(mcpillDir, "resources.md"))).toBe(true);
-    expect(fs.existsSync(path.join(mcpillDir, "mcpill.config.json"))).toBe(true);
+    expect(fs.existsSync(path.join(mcpillDir, "server.md"))).toBe(true);
+    expect(fs.existsSync(path.join(mcpillDir, "pill-agent-guide.md"))).toBe(true);
+    expect(fs.existsSync(path.join(mcpillDir, "pill-user-guide.md"))).toBe(true);
+    expect(fs.existsSync(path.join(serverDir, "mcpill.config.json"))).toBe(true);
+    expect(fs.existsSync(path.join(serverDir, "tools", "echo.md"))).toBe(true);
+    expect(fs.existsSync(path.join(serverDir, "prompts", "greeting.md"))).toBe(true);
+    expect(fs.existsSync(path.join(base, "PILL.md"))).toBe(true);
+    expect(fs.existsSync(path.join(base, "README.md"))).toBe(false);
+    expect(fs.existsSync(path.join(base, "package.json"))).toBe(false);
 
     const config = JSON.parse(
-      fs.readFileSync(path.join(mcpillDir, "mcpill.config.json"), "utf-8")
+      fs.readFileSync(path.join(serverDir, "mcpill.config.json"), "utf-8")
     );
     expect(config).toMatchObject({ name: path.basename(base), transport: "stdio", port: 3333 });
 
-    const prompts = JSON.parse(
-      fs.readFileSync(path.join(mcpillDir, "prompts.json"), "utf-8")
-    );
-    expect(Array.isArray(prompts)).toBe(true);
-    expect(prompts[0].name).toBe("summarize");
-
-    const resources = fs.readFileSync(path.join(mcpillDir, "resources.md"), "utf-8");
-    expect(resources).toContain("uri: config://app");
+    const serverMd = fs.readFileSync(path.join(mcpillDir, "server.md"), "utf-8");
+    expect(serverMd).toContain(`name: ${path.basename(base)}`);
 
-    const tools = fs.readFileSync(path.join(mcpillDir, "tools.js"), "utf-8");
-    expect(tools).toContain("read_file");
+    const pillMd = fs.readFileSync(path.join(base, "PILL.md"), "utf-8");
+    expect(pillMd).toContain(".mcpill/pill-agent-guide.md");
   });
 
   it("exits with code 1 and correct message when .mcpill/ already exists", async () => {

package/src/__tests__/pack.test.ts

@@ -5,7 +5,7 @@ import os from "os";
 import { runPack, SERVER_ENTRY_TEMPLATE } from "../commands/pack.js";
 
 function scaffoldPill(baseDir: string, name = "test-pill") {
-  const mcpillDir = path.join(baseDir, ".test-pill");
+  const mcpillDir = path.join(baseDir, ".mcpill", "server");
   fs.mkdirSync(mcpillDir, { recursive: true });
   fs.writeFileSync(
     path.join(mcpillDir, "tools.js"),

package/src/__tests__/validate.test.ts

@@ -52,7 +52,7 @@ describe("runValidate", () => {
 
   it("passes on a valid scaffolded pill dir", async () => {
     const base = mkTmp();
-    const mcpillDir = path.join(base, ".mcpill");
+    const mcpillDir = path.join(base, ".mcpill", "server");
     scaffoldValid(mcpillDir);
 
     const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
@@ -74,7 +74,7 @@ describe("runValidate", () => {
 
   it("collects and prints tool error then exits 1", async () => {
     const base = mkTmp();
-    const mcpillDir = path.join(base, ".mcpill");
+    const mcpillDir = path.join(base, ".mcpill", "server");
     scaffoldValid(mcpillDir);
     // Break tools.js: handler is not a function
     fs.writeFileSync(
@@ -92,7 +92,7 @@ describe("runValidate", () => {
 
   it("collects and prints prompt error then exits 1", async () => {
     const base = mkTmp();
-    const mcpillDir = path.join(base, ".mcpill");
+    const mcpillDir = path.join(base, ".mcpill", "server");
     scaffoldValid(mcpillDir);
     fs.writeFileSync(path.join(mcpillDir, "prompts.json"), "not json {{{");
 
@@ -110,7 +110,7 @@ describe("runValidate", () => {
 
   it("collects and prints resource error then exits 1", async () => {
     const base = mkTmp();
-    const mcpillDir = path.join(base, ".mcpill");
+    const mcpillDir = path.join(base, ".mcpill", "server");
     scaffoldValid(mcpillDir);
     // Block missing uri
     fs.writeFileSync(
@@ -130,7 +130,7 @@ describe("runValidate", () => {
 
   it("collects errors from multiple loaders before exiting", async () => {
     const base = mkTmp();
-    const mcpillDir = path.join(base, ".mcpill");
+    const mcpillDir = path.join(base, ".mcpill", "server");
     scaffoldValid(mcpillDir);
     // Break both tools and prompts
     fs.writeFileSync(

package/src/commands/compile.ts

@@ -1,5 +1,5 @@
-import { resolve, join, basename } from 'path';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'fs';
+import { resolve, join } from 'path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { pathToFileURL } from 'url';
 import { parseServerDir } from '../compiler/parse.js';
 import { serializeServerDir } from '../compiler/serialize.js';
@@ -62,38 +62,28 @@ function serializeResourcesMd(resources: ServerDoc['resources']): string {
   );
 }
 
-function findPillDirs(baseDir: string): string[] {
-  return readdirSync(baseDir, { withFileTypes: true })
-    .filter(
-      (e) =>
-        e.isDirectory() &&
-        /^\.[a-z][a-z0-9-]*$/.test(e.name) &&
-        existsSync(join(baseDir, e.name, 'mcpill.config.json')),
-    )
-    .map((e) => join(baseDir, e.name));
-}
-
 export async function runCompile(opts: {
   dir?: string;
   toMd?: boolean;
   strict?: boolean;
 }): Promise<void> {
   const baseDir = resolve(opts.dir ?? process.cwd());
+  const mcpillDir = join(baseDir, '.mcpill');
+  const serverDir = join(mcpillDir, 'server');
 
   if (opts.toMd) {
-    const pillDirs = findPillDirs(baseDir);
-    if (pillDirs.length === 0) {
-      throw new Error('No pill directories found — run mcpill compile first');
+    const configPath = join(serverDir, 'mcpill.config.json');
+    if (!existsSync(configPath)) {
+      throw new Error('No pill found — run mcpill compile first');
     }
-    const mcpillDir = pillDirs[0]!;
 
-    const config = await loadConfig(mcpillDir);
-    const resources = await loadResources(mcpillDir);
+    const config = await loadConfig(serverDir);
+    const resources = await loadResources(serverDir);
 
-    const promptsPath = join(mcpillDir, 'prompts.json');
+    const promptsPath = join(serverDir, 'prompts.json');
     const prompts = JSON.parse(readFileSync(promptsPath, 'utf-8')) as ServerDoc['prompts'];
 
-    const toolsPath = join(mcpillDir, 'tools.js');
+    const toolsPath = join(serverDir, 'tools.js');
     const handlers = existsSync(toolsPath)
       ? extractHandlers(readFileSync(toolsPath, 'utf-8'))
       : new Map<string, string>();
@@ -130,15 +120,14 @@ export async function runCompile(opts: {
       resources,
     };
 
-    serializeServerDir(doc, baseDir);
+    serializeServerDir(doc, mcpillDir);
     return;
   }
 
-  // Forward direction: server.md + tools/ + prompts/ → .<name>/
-  const doc = parseServerDir(baseDir);
-  const mcpillDir = join(baseDir, '.' + doc.config.name);
+  // Forward direction: .mcpill/server.md + .mcpill/server/tools/ + .mcpill/server/prompts/ → .mcpill/server/
+  const doc = parseServerDir(mcpillDir);
 
-  const toolsJsPath = join(mcpillDir, 'tools.js');
+  const toolsJsPath = join(serverDir, 'tools.js');
   const existing = existsSync(toolsJsPath)
     ? extractHandlers(readFileSync(toolsJsPath, 'utf-8'))
     : new Map<string, string>();
@@ -152,12 +141,11 @@ export async function runCompile(opts: {
     console.warn(`⚠  Stub generated for tool: ${name}`);
   }
 
-  mkdirSync(mcpillDir, { recursive: true });
-  writeFileSync(join(mcpillDir, 'mcpill.config.json'), JSON.stringify(mergedDoc.config, null, 2));
-  writeFileSync(join(mcpillDir, 'prompts.json'), JSON.stringify(mergedDoc.prompts, null, 2));
-  writeFileSync(join(mcpillDir, 'resources.md'), serializeResourcesMd(mergedDoc.resources));
+  mkdirSync(serverDir, { recursive: true });
+  writeFileSync(join(serverDir, 'mcpill.config.json'), JSON.stringify(mergedDoc.config, null, 2));
+  writeFileSync(join(serverDir, 'prompts.json'), JSON.stringify(mergedDoc.prompts, null, 2));
+  writeFileSync(join(serverDir, 'resources.md'), serializeResourcesMd(mergedDoc.resources));
   writeFileSync(toolsJsPath, generateToolsJs(mergedDoc.tools));
 
-  const pillDirName = '.' + doc.config.name;
-  console.log(`✓ ${pillDirName}/ updated from server.md, tools/, prompts/`);
+  console.log(`✓ .mcpill/server/ updated from .mcpill/server.md, .mcpill/server/tools/, .mcpill/server/prompts/`);
 }

package/src/commands/init.ts

@@ -1,25 +1,24 @@
 import fs from "fs";
 import path from "path";
 
-function makePillMd(projectName: string): string {
-  return `<!-- ═══════════════════════════════════════════════════════════════
-FOR THE AGENT — read this before doing anything else
-═══════════════════════════════════════════════════════════════
+const PILL_AGENT_GUIDE_MD = `# pill-agent-guide
 
-You are building an mcpill MCP server from this document.
+Instructions for building an mcpill MCP server from a filled \`PILL.md\`.
+
+---
 
-STEPS:
+## Steps
 
-1. PARSE the sections below:
-   - ## Server           → server name, description, transport (+ port if http)
-   - ## Tool: <name>     → one tool per section (repeatable)
-   - ## Resource: <name> → static resource (optional, repeatable)
-   - ## Prompt: <name>   → prompt template (optional, repeatable)
+1. **Parse** the sections in \`PILL.md\`:
+   - \`## Server\`           → server name, description, transport (+ port if http)
+   - \`## Tool: <name>\`     → one tool per section (repeatable)
+   - \`## Resource: <name>\` → static resource (optional, repeatable)
+   - \`## Prompt: <name>\`   → prompt template (optional, repeatable)
 
-2. CREATE a directory named after the server. Generate inside it:
+2. **Write** the server files into the pre-created scaffold at \`.mcpill/\`:
 
-   server.md
-   ─────────
+   \`.mcpill/server.md\`
+   \`\`\`
    ## Config
    name: {name}
    transport: {transport}
@@ -30,11 +29,12 @@ STEPS:
    name: {resource-name}
    ---
    {content}
-   ← omit ## Resources entirely if none specified
-   ← separate multiple resources with a blank line + --- + blank line
+   \`\`\`
+   Omit \`## Resources\` entirely if none were specified.
+   Separate multiple resources with a blank line + \`---\` + blank line.
 
-   tools/{tool-name}.md  (one file per ## Tool section)
-   ─────────────────────
+   \`.mcpill/server/tools/{tool-name}.md\` — one file per \`## Tool\` section:
+   \`\`\`
    # {tool-name}
 
    {description}
@@ -47,13 +47,13 @@ STEPS:
 
    \`\`\`js
    async ({ {param} }) => {
-     // real implementation — not a stub
      return { content: [{ type: "text", text: {result} }] };
    }
    \`\`\`
+   \`\`\`
 
-   prompts/{prompt-name}.md  (one file per ## Prompt section)
-   ─────────────────────────
+   \`.mcpill/server/prompts/{prompt-name}.md\` — one file per \`## Prompt\` section:
+   \`\`\`
    # {prompt-name}
 
    {description}
@@ -65,26 +65,47 @@ STEPS:
    ## Message
 
    > user: {message with {{arg}} placeholders}
-   ← omit ## Args if the prompt takes no arguments
+   \`\`\`
+   Omit \`## Args\` if the prompt takes no arguments.
 
-3. TRANSLATE each tool's \`behavior\` field into a working JS async handler.
+3. **Translate** each tool's \`behavior\` field into a working JS async handler.
    - Implement the described logic fully — no stubs, no TODOs.
    - Handler is self-contained: no top-level imports.
    - For file I/O or network calls: use dynamic import inside the handler.
-   - Return shape must be: { content: [{ type: "text", text: string }] }
-   - Allowed parameter types: string | number | boolean. Default unknown types to string.
+   - Return shape: \`{ content: [{ type: "text", text: string }] }\`
+   - Allowed parameter types: \`string | number | boolean\`. Default unknown types to \`string\`.
 
-4. RUN \`mcpill compile\` (or \`mcpill compile --dir {server-name}\`).
+4. **Run** \`mcpill compile\`.
 
-5. REPORT what was generated and show the user the next commands:
+5. **Report** what was generated and show the user the next commands:
+   \`\`\`
    mcpill validate
    mcpill run
-   mcpill pack / mcpill publish
+   mcpill pack
+   mcpill publish
+   \`\`\`
+
+---
+
+## Edge cases
+
+| Situation | Handling |
+|---|---|
+| \`transport: http\` without port | Default to \`3333\` |
+| Prompt message without role prefix | Wrap as \`> user: {message}\` |
+| Server name with spaces | Convert to kebab-case for \`name\` field |
+| Input type not \`string\\|number\\|boolean\` | Default to \`string\`, note the assumption |
+| Vague \`behavior\` field | Implement the most literal reasonable interpretation |
+`;
+
+function makePillMd(projectName: string): string {
+  return `<!-- ═══════════════════════════════════════════════════════════════
+FOR THE AGENT — read this before doing anything else
+═══════════════════════════════════════════════════════════════
+
+You are building an mcpill MCP server from this document.
+Follow the steps in .mcpill/pill-agent-guide.md.
 
-EDGE CASES:
-- transport http without port → default to 3333
-- prompt message without role prefix → wrap as \`> user: {message}\`
-- server name with spaces → convert to kebab-case for directory and name field
 ════════════════════════════════════════════════════════════════ -->
 
 # Pill: ${projectName}
@@ -137,6 +158,67 @@ After the source files are generated:
 `;
 }
 
+const HELLO_MCP_MD = `<!-- ═══════════════════════════════════════════════════════════════
+HELLO-MCP — a ready-to-run example
+
+Want to see mcpill in action before building your own server?
+
+1. Copy the content below into your PILL.md (replace everything).
+2. Tell Claude: "Build this PILL.md"
+3. Run: mcpill compile && mcpill validate && mcpill run
+═══════════════════════════════════════════════════════════════ -->
+
+# Pill: hello-mcp
+
+---
+
+## Server
+
+name: hello-mcp
+description: A hello-world MCP server — see mcpill in action.
+transport: stdio
+
+---
+
+## Resource: server-info
+
+uri: info://server
+name: Server Info
+content: |
+  hello-mcp is a demo MCP server built with mcpill.
+  Tools: ping, echo. Prompt: introduce.
+
+---
+
+## Tool: ping
+
+description: Returns pong with the current UTC timestamp.
+inputs:
+output: A pong message with the current timestamp.
+behavior: |
+  Return the string "pong — " followed by new Date().toISOString().
+
+---
+
+## Tool: echo
+
+description: Echoes a message back to the caller.
+inputs:
+  - message (string): The message to echo.
+output: The same message, echoed back as text.
+behavior: |
+  Return the message input unchanged.
+
+---
+
+## Prompt: introduce
+
+description: Ask the server to introduce itself.
+behavior: |
+  A prompt (no args) with a single user message:
+  "Introduce yourself — what is hello-mcp and what can it do?"
+`;
+
 // Embedded content of src/templates/server.md — tsup does not copy non-TS assets,
 // so the template is inlined here. Keep in sync with src/templates/server.md.
 const SERVER_MD_TEMPLATE = `## Config
@@ -180,9 +262,77 @@ Generate a greeting
 > user: Say hello to {{name}}
 `;
 
+function makePillUserGuideMd(projectName: string): string {
+  return `# ${projectName} — mcpill user guide
+
+## Quickstart
+
+1. **Describe your server** in \`PILL.md\` — fill in the \`## Server\` block and add \`## Tool\` sections.
+2. **Build it** — open Claude Code and say:
+   > "Build this PILL.md"
+   Claude reads \`.mcpill/pill-agent-guide.md\` and generates the source files.
+3. **Compile**
+   \`\`\`sh
+   mcpill compile
+   \`\`\`
+4. **Test locally**
+   \`\`\`sh
+   mcpill validate   # schema check
+   mcpill run        # start the server
+   \`\`\`
+5. **Pack & publish**
+   \`\`\`sh
+   mcpill pack
+   mcpill publish
+   \`\`\`
+
+## Project layout
+
+\`\`\`
+${projectName}/
+├── PILL.md                            ← describe your server here
+└── .mcpill/
+    ├── server.md                      ← server config (name, transport, resources)
+    ├── pill-agent-guide.md            ← instructions Claude follows when building
+    ├── pill-user-guide.md             ← this file
+    └── server/
+        ├── mcpill.config.json         ← compiled config
+        ├── tools/                     ← one .md file per tool
+        │   └── echo.md
+        └── prompts/                   ← one .md file per prompt (optional)
+            └── greeting.md
+\`\`\`
+
+## Editing tools manually
+
+Each file in \`.mcpill/server/tools/\` follows this shape:
+
+\`\`\`markdown
+# tool-name
+
+One-line description.
+
+## Parameters
+
+- param (string): what it is
+
+## Handler
+
+\`\`\`js
+async ({ param }) => {
+  return { content: [{ type: "text", text: param }] };
+}
+\`\`\`
+\`\`\`
+
+Run \`mcpill compile\` after any edit to regenerate the server bundle.
+`;
+}
+
 export async function runInit(opts: { dir?: string }): Promise<void> {
   const targetDir = path.resolve(opts.dir ?? process.cwd());
   const mcpillDir = path.join(targetDir, ".mcpill");
+  const serverDir = path.join(mcpillDir, "server");
   const projectName = path.basename(targetDir);
 
   if (fs.existsSync(mcpillDir)) {
@@ -190,46 +340,30 @@ export async function runInit(opts: { dir?: string }): Promise<void> {
     process.exit(1);
   }
 
-  const configJson = JSON.stringify(
-    { name: projectName, transport: "stdio", port: 3333 },
-    null,
-    2,
-  );
-
-  fs.mkdirSync(mcpillDir, { recursive: true });
-  fs.writeFileSync(path.join(mcpillDir, "mcpill.config.json"), configJson);
-
-  const toolsDir = path.join(targetDir, "tools");
-  const promptsDir = path.join(targetDir, "prompts");
-  fs.mkdirSync(toolsDir, { recursive: true });
-  fs.mkdirSync(promptsDir, { recursive: true });
-  fs.writeFileSync(path.join(toolsDir, "echo.md"), ECHO_TOOL_MD);
-  fs.writeFileSync(path.join(promptsDir, "greeting.md"), GREETING_PROMPT_MD);
+  fs.mkdirSync(path.join(serverDir, "tools"), { recursive: true });
+  fs.mkdirSync(path.join(serverDir, "prompts"), { recursive: true });
 
-  const serverMd = SERVER_MD_TEMPLATE.replace(
-    "name: my-server",
-    `name: ${projectName}`,
+  const serverMd = SERVER_MD_TEMPLATE.replace("name: my-server", `name: ${projectName}`);
+  fs.writeFileSync(path.join(mcpillDir, "server.md"), serverMd);
+  fs.writeFileSync(path.join(serverDir, "tools", "echo.md"), ECHO_TOOL_MD);
+  fs.writeFileSync(path.join(serverDir, "prompts", "greeting.md"), GREETING_PROMPT_MD);
+  fs.writeFileSync(
+    path.join(serverDir, "mcpill.config.json"),
+    JSON.stringify({ name: projectName, transport: "stdio", port: 3333 }, null, 2),
   );
-  fs.writeFileSync(path.join(targetDir, "server.md"), serverMd);
-  fs.writeFileSync(path.join(targetDir, "PILL.md"), makePillMd(projectName));
+  fs.writeFileSync(path.join(mcpillDir, "pill-agent-guide.md"), PILL_AGENT_GUIDE_MD);
+  fs.writeFileSync(path.join(mcpillDir, "pill-user-guide.md"), makePillUserGuideMd(projectName));
+  fs.writeFileSync(path.join(mcpillDir, "HELLO-MCP.md"), HELLO_MCP_MD);
 
-  const pkgJson = JSON.stringify(
-    {
-      name: projectName,
-      version: "0.1.0",
-      private: true,
-      scripts: { pack: "mcpill pack", publish: "mcpill publish" },
-    },
-    null,
-    2,
-  );
-  fs.writeFileSync(path.join(targetDir, "package.json"), pkgJson);
+  fs.writeFileSync(path.join(targetDir, "PILL.md"), makePillMd(projectName));
 
-  console.log("✓ PILL.md          ← describe your server, then tell Claude: \"Build this PILL.md\"");
-  console.log("✓ server.md        ← or edit source files directly");
-  console.log("✓ tools/echo.md");
-  console.log("✓ prompts/greeting.md");
-  console.log("✓ package.json");
+  console.log("✓ PILL.md                        ← describe your server, then tell Claude: \"Build this PILL.md\"");
+  console.log("✓ .mcpill/HELLO-MCP.md           ← copy into PILL.md to see a working example instantly");
+  console.log("✓ .mcpill/server.md              ← or edit source files directly");
+  console.log("✓ .mcpill/server/tools/echo.md");
+  console.log("✓ .mcpill/server/prompts/greeting.md");
+  console.log("✓ .mcpill/pill-agent-guide.md    ← agent instructions (read by Claude)");
+  console.log("✓ .mcpill/pill-user-guide.md     ← start here");
   console.log("");
   console.log("When ready: mcpill compile && mcpill run");
 }

package/src/commands/pack.ts

@@ -6,25 +6,11 @@ import { loadConfig } from "../loaders/config.js";
 export const SERVER_ENTRY_TEMPLATE =
   "import { runPill } from 'mcpill-runtime';\nrunPill();\n";
 
-function resolvePillDir(baseDir: string): string {
-  const entries = fs.readdirSync(baseDir, { withFileTypes: true });
-  const pill = entries.find(
-    (e) =>
-      e.isDirectory() &&
-      /^\.[a-z][a-z0-9-]*$/.test(e.name) &&
-      fs.existsSync(path.join(baseDir, e.name, "mcpill.config.json")),
-  );
-  if (!pill) {
-    throw new Error("No pill directory found — run mcpill compile first");
-  }
-  return path.join(baseDir, pill.name);
-}
-
 export async function runPack(dir: string): Promise<void> {
   const baseDir = path.resolve(dir);
   await runValidate(baseDir);
 
-  const pillDir = resolvePillDir(baseDir);
+  const pillDir = path.join(baseDir, ".mcpill", "server");
   const config = await loadConfig(pillDir);
   const { name } = config;
 

package/src/commands/run.ts

@@ -1,7 +1,7 @@
 import path from "path";
 import fs from "fs";
 import { z } from "mcpill-runtime";
-import { createServer } from "mcpster";
+import { createServer, applySetup } from "mcpster";
 import { loadConfig } from "../loaders/config.js";
 import { loadTools } from "../loaders/tools.js";
 import { loadPrompts } from "../loaders/prompts.js";
@@ -19,17 +19,11 @@ export async function runServer(opts: {
 
   await runValidate(baseDir);
 
-  const pillDirs = fs
-    .readdirSync(baseDir, { withFileTypes: true })
-    .filter(
-      (e) =>
-        e.isDirectory() &&
-        /^\.[a-z][a-z0-9-]*$/.test(e.name) &&
-        fs.existsSync(path.join(baseDir, e.name, "mcpill.config.json")),
-    )
-    .map((e) => path.join(baseDir, e.name));
-
-  const mcpillDir = pillDirs[0]!;
+  const mcpillDir = path.join(baseDir, ".mcpill", "server");
+  if (!fs.existsSync(path.join(mcpillDir, "mcpill.config.json"))) {
+    console.error("No pill found — run mcpill compile first");
+    process.exit(1);
+  };
 
   const [tools, prompts, resources, config] = await Promise.all([
     loadTools(mcpillDir),
@@ -82,6 +76,16 @@ export async function runServer(opts: {
     });
   }
 
+  applySetup(name, tools.map((t) => t.name), {
+    projectPath: baseDir,
+    permissions: 'restrictive',
+    register: true,
+    cmdOverride: {
+      command: 'mcpill',
+      args: ['run', '--dir', baseDir],
+    },
+  })
+
   try {
     await server.start();
   } catch (err) {

package/src/commands/validate.ts

@@ -49,22 +49,11 @@ async function validateOne(mcpillDir: string): Promise<void> {
 }
 
 export async function runValidate(baseDir: string): Promise<void> {
-  const pillDirs = fs
-    .readdirSync(baseDir, { withFileTypes: true })
-    .filter(
-      (e) =>
-        e.isDirectory() &&
-        /^\.[a-z][a-z0-9-]*$/.test(e.name) &&
-        fs.existsSync(path.join(baseDir, e.name, "mcpill.config.json")),
-    )
-    .map((e) => path.join(baseDir, e.name));
-
-  if (pillDirs.length === 0) {
+  const serverDir = path.join(baseDir, ".mcpill", "server");
+  if (!fs.existsSync(path.join(serverDir, "mcpill.config.json"))) {
     console.error("No pill directories found — run mcpill compile first");
     process.exit(1);
   }
 
-  for (const mcpillDir of pillDirs) {
-    await validateOne(mcpillDir);
-  }
+  await validateOne(serverDir);
 }

package/src/compiler/parse.ts

@@ -208,7 +208,7 @@ export function parseServerDir(dir: string): ServerDoc {
   const resourcesBody = sections.get('Resources') ?? '';
   const resources = parseResourcesSection(resourcesBody);
 
-  const toolsDir = join(dir, 'tools');
+  const toolsDir = join(dir, 'server', 'tools');
   const tools: ToolDoc[] = [];
   let toolFiles: string[] = [];
   try {
@@ -220,7 +220,7 @@ export function parseServerDir(dir: string): ServerDoc {
     tools.push(parseToolFile(readFileSync(join(toolsDir, file), 'utf-8')));
   }
 
-  const promptsDir = join(dir, 'prompts');
+  const promptsDir = join(dir, 'server', 'prompts');
   const prompts: PromptDoc[] = [];
   let promptFiles: string[] = [];
   try {

package/src/compiler/serialize.ts

@@ -43,8 +43,8 @@ export function serializeServerDoc(doc: ServerDoc): string {
 }
 
 export function serializeServerDir(doc: ServerDoc, dir: string): void {
-  mkdirSync(join(dir, 'tools'), { recursive: true });
-  mkdirSync(join(dir, 'prompts'), { recursive: true });
+  mkdirSync(join(dir, 'server', 'tools'), { recursive: true });
+  mkdirSync(join(dir, 'server', 'prompts'), { recursive: true });
 
   let serverMd = '## Config\n';
   serverMd += `name: ${doc.config.name}\n`;
@@ -73,7 +73,7 @@ export function serializeServerDir(doc: ServerDoc, dir: string): void {
         .trim();
       md += `\n## Handler\n\n\`\`\`js\n${cleanHandler}\n\`\`\`\n`;
     }
-    writeFileSync(join(dir, 'tools', `${tool.name}.md`), md);
+    writeFileSync(join(dir, 'server', 'tools', `${tool.name}.md`), md);
   }
 
   for (const prompt of doc.prompts) {
@@ -92,7 +92,7 @@ export function serializeServerDir(doc: ServerDoc, dir: string): void {
         md += `> ${msg.role}: ${msg.content}\n`;
       }
     }
-    writeFileSync(join(dir, 'prompts', `${prompt.name}.md`), md);
+    writeFileSync(join(dir, 'server', 'prompts', `${prompt.name}.md`), md);
   }
 
   console.log(`✓ tools/ updated (${doc.tools.length} files)`);