d7a4cb8031
* feat: add npm package support for @openagents/control
- Convert package to publishable npm package with scoped name @openagents/control
- Add CLI entry point bin/oac.js for global installation
- Create .npmignore to exclude dev files and node_modules
- Configure package.json with proper files, bin, and metadata
- Add comprehensive NPM_PUBLISHING_GUIDE.md with publishing instructions
- Package size: 610KB (2.4MB unpacked) with 353 files
- Includes .opencode/tool/ directory without node_modules
- CLI command: oac (e.g., 'oac developer' or 'oac --help')
Users can install with: npm install -g @openagents/control
* chore: remove telegram bot files from package
- Delete .opencode/_lib/telegram-bot.ts (unused)
- Delete .opencode/plugin/telegram-notify.ts (depends on deleted file)
- Remove _lib directory reference from package.json files field
- Reduces package size from 610KB to 607KB
- Total files: 351 (down from 353)
* chore: remove all telegram references from registry and docs
- Remove telegram-bot and telegram-notify plugin entries from registry.json
- Remove telegram plugin references from all profiles (developer, business, full, advanced)
- Update profile-validation.md to remove telegram from business profile documentation
- Clean package with no telegram dependencies
* docs: enhance README clarity and add configuration examples
- Add Core Philosophy section with 4 key principles
- Add Quick Concepts for First-Time Users (scannable format)
- Add prominent Oh My OpenCode comparison link
- Add comprehensive Model Configuration section
- Add Customizing Agents section with practical examples
- Streamline model selection recommendations
- Add emoji headers for visual consistency
- Remove redundant FAQ entry
Addresses user feedback about documentation clarity and first-time user experience.
* refactor: remove OpenImplementer agent
- Delete OpenImplementer agent file (redundant with OpenAgent)
- Remove from registry.json and all profiles
- Update OpenCoder delegation rules (now handles 1-4 files directly)
- Clean up all context file references
- Remove from commands and documentation
Rationale: OpenImplementer only added 1 file to OpenAgent's capability (3→4 files), creating unnecessary complexity. OpenAgent and OpenCoder provide clearer separation: OpenAgent for general + focused tasks (1-4 files), OpenCoder for complex architecture (4+ files).
* fix: remove stale OpenImplementer reference from OpenCoder
- Remove OpenImplementer from Available Subagents list
- Clarify CoderAgent is used via TaskManager for complex tasks
- Keep delegation rules as-is (execute 1-4 files directly, delegate complex to CoderAgent)
* docs: remove remaining OpenImplementer references
- Update developer profile description (OpenAgent vs OpenCoder)
- Update registry.json profile description
- Update docs/README.md to remove OpenImplementer
- Update CHANGELOG.md to reflect simplified architecture
All OpenImplementer references now removed. Registry validation passes.
* docs: enhance README with first-time user improvements
- Add 'your secret weapon!' to Context System in Quick Concepts
- Add First-Time User Checklist after Get Started section
- Add visual comparison table for AOC vs Oh My OpenCode in FAQ
- Improve scannability and clarity for new users
Based on DocWriter review recommendations.
* docs: clarify project-context.md is created during installation
Minor enhancement to First-Time User Checklist step 2 for extra clarity.
* docs: change 'I' to 'we' for collaborative tone
- Update 'Why I Built This' to 'Why We Built This'
- Change 'I've spent' to 'We've spent'
- Change 'I use this' to 'We use this'
- Makes the project feel more collaborative and team-oriented
* docs: make intro more neutral and objective
- Change 'Why We Built This' to 'Why This Exists'
- Remove personal perspective ('We've spent 14+ years')
- Change 'We use this' to 'It's built for shipping'
- More professional and objective tone
* docs: major README rewrite based on user feedback
Key improvements based on real user confusion:
1. **Clear 'What Is AOC?' section** - Explains scaffold vs plugin approach upfront
2. **Model configuration prominently featured** - Addresses #1 user question
3. **Hook with quantified paradox** - Grabs attention in 15 seconds
4. **Context System promoted** - Moved to top, explains the differentiator
5. **Comparison table** - AOC vs Oh My OpenCode side-by-side
6. **Eliminated 60% redundancy** - Merged overlapping sections
7. **Simplified deep dives** - Model config and customization tightened
Based on user feedback: 'I just expected that behaviour because it was not
documented properly... the only thing really lacking was a clear explanation
of its purpose and how to configure models and adjust agents.'
Addresses: Confusion about scaffold vs plugin, model configuration, and
first-time user expectations.
* chore: publish package as @nextsystems/oac v0.7.0
- Changed package name from @openagents/control to @nextsystems/oac
- Successfully published to npm registry
- Users can install with: npm install -g @nextsystems/oac
- CLI command: oac
* feat: add context path configuration and reorganize documentation
- Add configurable context root via paths.json (@reference support)
- Add /add-context command for interactive context setup
- Move NPM_PUBLISHING_GUIDE.md to context system (guides/npm-publishing.md)
- Add GitHub issues workflow guide
- Update agents to support custom context directories
- Update navigation with new guides and file counts
This enables projects to use custom context directories (e.g., .context, .ai/context)
while maintaining backward compatibility with default .opencode/context/ structure.
153 lines
2.7 KiB
Markdown
153 lines
2.7 KiB
Markdown
# NPM Publishing Guide
|
|
|
|
**Purpose**: Quick reference for publishing OpenAgents Control to npm
|
|
|
|
**Time to Read**: 3 minutes
|
|
|
|
---
|
|
|
|
## Core Concept
|
|
|
|
OpenAgents Control is published as `@nextsystems/oac` on npm. Users install globally and run `oac [profile]` to set up their projects.
|
|
|
|
**Key files**:
|
|
- `package.json` - Package configuration
|
|
- `bin/oac.js` - CLI entry point
|
|
- `.npmignore` - Exclude dev files
|
|
- `install.sh` - Main installer (runs when user executes `oac`)
|
|
|
|
---
|
|
|
|
## Publishing Workflow
|
|
|
|
### 1. Prepare Release
|
|
|
|
```bash
|
|
# Update version
|
|
npm version patch # 0.7.0 -> 0.7.1
|
|
npm version minor # 0.7.0 -> 0.8.0
|
|
|
|
# Update VERSION file
|
|
node -p "require('./package.json').version" > VERSION
|
|
|
|
# Update CHANGELOG.md with changes
|
|
```
|
|
|
|
### 2. Test Locally
|
|
|
|
```bash
|
|
# Create package
|
|
npm pack
|
|
|
|
# Install globally from tarball
|
|
npm install -g ./nextsystems-oac-0.7.1.tgz
|
|
|
|
# Test CLI
|
|
oac --version
|
|
oac --help
|
|
|
|
# Uninstall
|
|
npm uninstall -g @nextsystems/oac
|
|
```
|
|
|
|
### 3. Publish
|
|
|
|
```bash
|
|
# Login (one-time)
|
|
npm login
|
|
|
|
# Publish (scoped packages need --access public)
|
|
npm publish --access public
|
|
```
|
|
|
|
### 4. Verify
|
|
|
|
```bash
|
|
# Check it's live
|
|
npm view @nextsystems/oac
|
|
|
|
# Test installation
|
|
npm install -g @nextsystems/oac
|
|
oac --version
|
|
```
|
|
|
|
### 5. Create GitHub Release
|
|
|
|
```bash
|
|
git tag v0.7.1
|
|
git push --tags
|
|
# Create release on GitHub with changelog
|
|
```
|
|
|
|
---
|
|
|
|
## User Installation
|
|
|
|
Once published, users can:
|
|
|
|
```bash
|
|
# Global install (recommended)
|
|
npm install -g @nextsystems/oac
|
|
oac developer
|
|
|
|
# Or use npx (no install)
|
|
npx @nextsystems/oac developer
|
|
```
|
|
|
|
---
|
|
|
|
## Common Issues
|
|
|
|
**"You do not have permission to publish"**
|
|
```bash
|
|
npm whoami # Check you're logged in
|
|
npm publish --access public # Scoped packages need public access
|
|
```
|
|
|
|
**"Version already exists"**
|
|
```bash
|
|
npm version patch # Bump version first
|
|
```
|
|
|
|
**"You must verify your email"**
|
|
```bash
|
|
npm profile get # Check email verification status
|
|
```
|
|
|
|
---
|
|
|
|
## Package Configuration
|
|
|
|
**What's included** (see `package.json` → `files`):
|
|
- `.opencode/` - Agents, commands, context, profiles, skills, tools
|
|
- `scripts/` - Installation scripts
|
|
- `bin/` - CLI entry point
|
|
- `registry.json` - Component registry
|
|
- `install.sh` - Main installer
|
|
- Docs (README, CHANGELOG, LICENSE)
|
|
|
|
**What's excluded** (see `.npmignore`):
|
|
- `node_modules/`
|
|
- `evals/`
|
|
- `.tmp/`
|
|
- Dev files
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
- ✅ Enable 2FA: `npm profile enable-2fa auth-and-writes`
|
|
- ✅ Use strong npm password
|
|
- ✅ `@nextsystems` scope is protected (only you can publish)
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- **Package**: https://www.npmjs.com/package/@nextsystems/oac
|
|
- **Stats**: https://npm-stat.com/charts.html?package=@nextsystems/oac
|
|
- **Codebase**: `package.json`, `bin/oac.js`, `.npmignore`
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-01-30
|