feat: project refactoring - folder cleanup, governance, and automation

Project Structure Cleanup:
- Remove deprecated cmdb-assistant plugin
- Remove development output files (test scripts, status reports)
- Remove IDE-specific workspace files
- Create scripts/ directory for automation
- Create docs/architecture/ for Draw.io diagrams
- Create docs/workflows/ for workflow documentation
- Create .scratch/ directory for transient work

Governance & Documentation:
- Add File Creation Governance section to CLAUDE.md
- Add architecture diagram specifications (component-map, agent-workflow)
- Add docs/UPDATING.md with update workflow
- Update CHANGELOG.md with all changes

Installation Automation:
- Add scripts/setup.sh for initial installation
- Add scripts/post-update.sh for updates after git pull
- Add /initial-setup slash command

Maintenance:
- Update .gitignore with scratch directory
- Fix all project name references (use support-claude-mktplace)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2025-12-11 22:17:27 -05:00
parent b6a77d9b35
commit 8bb69d3556
29 changed files with 930 additions and 3315 deletions

101
docs/UPDATING.md Normal file
View File

@@ -0,0 +1,101 @@
# Updating support-claude-mktplace
This guide covers how to update your local installation when new versions are released.
## Quick Update
```bash
# 1. Pull latest changes
cd /path/to/support-claude-mktplace
git pull origin main
# 2. Run post-update script
./scripts/post-update.sh
```
## What the Post-Update Script Does
1. **Updates Python dependencies** for Gitea and Wiki.js MCP servers
2. **Shows recent changelog entries** so you know what changed
3. **Validates your configuration** is still compatible
## Manual Steps After Update
Some updates may require manual configuration changes:
### New Environment Variables
If the changelog mentions new environment variables:
1. Check the variable name and purpose in the changelog
2. Add it to the appropriate config file:
- Gitea variables → `~/.config/claude/gitea.env`
- Wiki.js variables → `~/.config/claude/wikijs.env`
- Project variables → `.env` in your project root
### New MCP Server Features
If a new MCP server tool is added:
1. The post-update script handles dependency installation
2. Check `docs/references/MCP-*.md` for usage documentation
3. New tools are available immediately after update
### Breaking Changes
Breaking changes will be clearly marked in CHANGELOG.md with migration instructions.
## Troubleshooting
### Dependencies fail to install
```bash
# Rebuild virtual environment
cd mcp-servers/gitea
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate
# Repeat for wikijs
cd ../wikijs
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate
```
### Configuration no longer works
1. Check CHANGELOG.md for breaking changes
2. Compare your config files with updated `.env.example` (if provided)
3. Run `./scripts/setup.sh` to validate configuration
### MCP server won't start
1. Check Python version: `python3 --version` (requires 3.10+)
2. Verify venv exists: `ls mcp-servers/gitea/.venv`
3. Check logs for specific errors
## Version Pinning
To stay on a specific version:
```bash
# List available tags
git tag
# Checkout specific version
git checkout v1.0.0
# Run post-update
./scripts/post-update.sh
```
## Getting Help
- Check `docs/references/` for component documentation
- Review CHANGELOG.md for recent changes
- Search existing issues in Gitea