catui-agent 1.0.0-beta.0

package/docs/loop-usage-examples.md

@@ -0,0 +1,215 @@
+# Loop Extension Usage Examples
+
+## Basic Usage
+
+### Session-Scoped Loops (Default)
+
+Session-scoped loops are cleared when you close the session.
+
+```bash
+# Check the build every 10 minutes (default)
+/loop check the build
+
+# Run a command every 5 minutes
+/loop 5m /grub status
+
+# Check PR reviews every 20 minutes
+/loop every 20m Review test failures
+
+# Remind to drink water every 30 minutes
+/loop Drink water every 30m --name hydrate --max 8 --quiet
+```
+
+### Durable Loops (Persistent Across Sessions)
+
+Durable loops are saved to `.catui/loop-tasks.json` and resume when you reopen the project.
+
+```bash
+# Monitor build status every 5 minutes, persists across sessions
+/loop Check build status every 5m --durable
+
+# Check for new commits every hour
+/loop 1h Check for new commits --durable
+
+# Daily status check at 9 AM
+/loop Daily status check --durable --name daily-check
+```
+
+## Managing Loops
+
+### List All Loops
+
+```bash
+/loop list
+```
+
+Output:
+```
+[Loop] 3 scheduled tasks:
+- build-monitor (abc123) every 5m next in 3m [durable] Check build status
+- hydrate (def456) every 30m next in 15m [quiet, max 2/8] Drink water every 30m
+- ghi789 every 10m next in 8m /grub status
+```
+
+### Get Loop Status
+
+```bash
+/loop status build-monitor
+```
+
+Output:
+```
+[Loop] build-monitor (abc123) — scheduled
+Every: 5m
+Kind: prompt (durable)
+Next run: Sat Apr 18 2025 01:05:00 GMT+0800 (in 3m)
+Last run: Sat Apr 18 2025 01:00:00 GMT+0800
+Run count: 5
+Input: Check build status
+Last output: Build is green
+```
+
+### Pause and Resume
+
+```bash
+/loop pause build-monitor
+/loop resume build-monitor
+```
+
+### Run Immediately
+
+```bash
+/loop run build-monitor
+```
+
+### Cancel a Loop
+
+```bash
+/loop cancel build-monitor
+# or by ID
+/loop cancel abc123
+```
+
+### Clear All Loops
+
+```bash
+/loop clear
+```
+
+## Advanced Features
+
+### Named Loops
+
+```bash
+/loop Check build every 5m --name build-monitor
+/loop pause build-monitor
+```
+
+### Maximum Runs
+
+```bash
+/loop Drink water every 30m --name hydrate --max 8 --quiet
+```
+
+### Quiet Mode
+
+Suppresses per-tick UI messages (errors and terminal events still surface):
+
+```bash
+/loop 5m Check system status --quiet
+```
+
+### Combining Flags
+
+```bash
+/loop Check build every 5m --name build-monitor --durable --quiet
+```
+
+## Durable vs Session-Scoped Loops
+
+| Feature | Session-Scoped | Durable |
+|---------|---------------|---------|
+| Persistence | Lost when session closes | Saved to disk |
+| Multi-process safety | N/A (per-process) | Protected by lock |
+| Use case | Temporary tasks | Long-running monitoring |
+| Storage | In-memory | `.catui/loop-tasks.json` |
+
+## Real-World Examples
+
+### Development Workflow
+
+```bash
+# Monitor build status while developing
+/loop npm run build --name build-check
+
+# Run tests every time you save
+/loop npm test --name test-checker --quiet
+
+# Check for linting errors
+/loop npm run lint --name linter --durable
+```
+
+### Project Monitoring
+
+```bash
+# Check for new git commits
+/loop git pull --name git-update --durable
+
+# Monitor dependencies
+/loop npm outdated --name deps-check --durable
+
+# Check server health
+/loop curl http://localhost:3000/health --name health-check --durable
+```
+
+### Productivity
+
+```bash
+# Take breaks
+/loop Take a break every hour --name break-reminder --max 4
+
+# Daily standup reminder
+/loop Daily standup every 24h --name standup --durable
+
+# Code review reminder
+/loop Review pending PRs every 2h --name pr-review --durable
+```
+
+## Troubleshooting
+
+### Loop Not Running
+
+1. Check if loop is paused: `/loop status <name>`
+2. Check if max runs reached: look at run count in status
+3. Check if session is idle: loops only run when agent is idle
+
+### Durable Loop Not Persisting
+
+1. Check if `.catui/loop-tasks.json` exists
+2. Verify you used `--durable` flag
+3. Check file permissions on project directory
+
+### Multiple Instances Triggering Same Loop
+
+The scheduler lock prevents this. If you see multiple triggers:
+1. Check if lock file exists: `.catui/loop-scheduler.lock`
+2. Manually remove lock file if necessary
+3. Restart Catui
+
+## File Locations
+
+```
+<catui>
+├── .catui/
+│   ├── loop-tasks.json          # Durable loop storage
+│   └── loop-scheduler.lock      # Scheduler lock file
+```
+
+## Best Practices
+
+1. **Use meaningful names**: `--name` makes it easier to manage loops
+2. **Set appropriate intervals**: Don't poll too frequently (minimum 1m)
+3. **Use durable for long-running tasks**: `--durable` for tasks that should survive session restarts
+4. **Use max runs for finite tasks**: `--max` for tasks that should auto-cancel
+5. **Use quiet for frequent tasks**: `--quiet` reduces UI noise
+6. **Monitor loops**: Regularly check `/loop list` to ensure loops are working as expected

package/docs/models.md

@@ -0,0 +1,27 @@
+---
+name: models
+description: Use when the user asks how to add, select, or configure models.
+surface: TODO  # user entry points: /command, --flag, config key, file location
+owner: core/model-registry.ts  # DIP P2 anchor — read its AGENT.md member list to find code
+status: draft
+---
+
+# Models
+
+> TODO: one line — what this feature does for the user.
+
+## When to use
+TODO: the user intents that should pull this doc (mirrors the frontmatter `description`).
+
+## Usage
+TODO: commands / flags / config keys / file locations, with one minimal example.
+
+## Behavior & defaults
+TODO: default on/off, side effects, opt-in/opt-out.
+
+## Code map → DIP
+- Owner: `core/model-registry.ts` — read its DIP **P2 member list** (the nearest `AGENT.md`) to locate files.
+- Then follow **P3** file headers (WHO / FROM / TO / HERE) to navigate. Do **not** duplicate code paths here.
+
+## Related
+[[custom-provider]] [[providers]]

package/docs/packages.md

@@ -0,0 +1,27 @@
+---
+name: packages
+description: Use when the user asks about the published @catui/* packages.
+surface: TODO  # user entry points: /command, --flag, config key, file location
+owner: packages/  # DIP P2 anchor — read its AGENT.md member list to find code
+status: draft
+---
+
+# Packages
+
+> TODO: one line — what this feature does for the user.
+
+## When to use
+TODO: the user intents that should pull this doc (mirrors the frontmatter `description`).
+
+## Usage
+TODO: commands / flags / config keys / file locations, with one minimal example.
+
+## Behavior & defaults
+TODO: default on/off, side effects, opt-in/opt-out.
+
+## Code map → DIP
+- Owner: `packages/` — read its DIP **P2 member list** (the nearest `AGENT.md`) to locate files.
+- Then follow **P3** file headers (WHO / FROM / TO / HERE) to navigate. Do **not** duplicate code paths here.
+
+## Related
+[[sdk]] [[extensions]]