docs: update README with minimal branding insights

2026-03-29 21:33:54 +00:00 · 2026-03-24 13:23:13 +11:00 · 2026-03-24 13:23:13 +11:00 · 39bd38040c
commit 39bd38040c
parent a8b73fd754
1 changed files with 165 additions and 79 deletions
--- a/README.md
+++ b/README.md
@ -2,7 +2,7 @@

 > ToothFairyAI's official coding agent

-**Status**: 🟡 Planning Phase | **Last Updated**: 2026-03-24
+**Status**: 🟢 Foundation Ready | **Last Updated**: 2026-03-24

 ---

@ -10,6 +10,8 @@

 **tfcode** is ToothFairyAI's official AI coding agent - a terminal-based coding assistant that integrates seamlessly with your TF workspace tools, MCP servers, agent skills, and database connections.

+Based on [opencode](https://github.com/anomalyco/opencode) - an excellent AI coding tool. We credit and thank the opencode team for their outstanding work.
+
 ---

 ## Product Identity
@ -19,18 +21,21 @@
 | **Name** | tfcode |
 | **Positioning** | ToothFairyAI's official coding agent |
 | **Target Users** | Existing TF customers |
-| **Config Compatibility** | Supports opencode.json for migration |
+| **Config Files** | `tfcode.json` (primary), `opencode.json` (migration support) |
+| **Config Directory** | `.tfcode/` |

 ---

 ## Key Features

-### Core Capabilities
+### Core Capabilities (from opencode)
 - Terminal-based AI coding assistant
 - File read/write/edit operations
 - Bash command execution
 - Code search (glob, grep)
 - Multi-agent support (Tab switching)
+- MCP server integration
+- LSP integration

 ### ToothFairyAI Integration
 - **MCP Servers** from TF workspace (`isMCPServer`)
@ -56,6 +61,38 @@ See [FORK_MANAGEMENT.md](./FORK_MANAGEMENT.md) for full details.

 ---

+## Branding Strategy
+
+### Minimal Branding Approach
+
+We use a **minimal branding approach** to ensure clean upstream merges:
+
+| Aspect | Branding | Reason |
+|--------|----------|--------|
+| CLI binary | `tfcode` | User-facing |
+| Package name | `tfcode` | User-facing |
+| Config directory | `.tfcode/` | User-facing |
+| Internal code | `opencode` | Easy merges |
+| Workspace packages | `@opencode-ai/*` | Low priority |
+| Config file names | `opencode.json` | Low priority |
+
+### What This Means
+
+**Changed** (user-facing):
+- Binary: `packages/tfcode/bin/tfcode`
+- Package: `packages/tfcode/package.json` → name: `tfcode`
+- Config: `.tfcode/` directory
+
+**Unchanged** (internal):
+- All code references to "opencode" in source files
+- `@opencode-ai/*` workspace package names
+- Internal flags like `OPENCODE_*`
+- Provider IDs, model references
+
+**Result**: When merging upstream changes, only directory names and a few config paths differ. Git can handle merges automatically.
+
+---
+
 ## Architecture

 ```
@ -222,6 +259,35 @@ tfcode automatically detects and converts opencode.json to tfcode.json on first

 ---

+## Project Structure
+
+```
+tf_code/
+├── packages/
+│   ├── tfcode/              # Core engine (renamed from opencode)
+│   │   ├── bin/tfcode       # CLI binary
+│   │   ├── src/             # All source code
+│   │   └── package.json     # name: tfcode
+│   ├── tf-sync/             # Python TF SDK sync layer
+│   │   └── src/tf_sync/
+│   │       ├── config.py    # TFConfig, multi-region URLs
+│   │       ├── tools.py     # Tool sync using SDK
+│   │       ├── mcp.py       # MCP server sync
+│   │       └── agents.py    # Agent sync (future)
+│   ├── tf-mcp-bridge/       # TypeScript MCP proxy bridge
+│   └── tf-config-loader/    # Config loader (stub)
+├── .tfcode/                 # Config directory
+├── scripts/
+│   └── rebrand.sh           # Reapply branding after upstream merge
+├── tfcode.json              # Config template
+├── schemas/
+│   └── tfcode.schema.json   # JSON schema
+├── README.md                # This file
+└── FORK_MANAGEMENT.md       # Fork sync strategy
+```
+
+---
+
 ## Installation

 ```bash
@ -293,42 +359,41 @@ tfcode tools test <name>           # Test tool call

 ## Implementation Phases

-### Phase 1: Rebrand & Foundation ⏳ IN PROGRESS
+### Phase 1: Foundation ✅ COMPLETE

-**Tasks**:
+**Completed**:
 - [x] Fork repository structure
- [ ] Rebrand opencode → tfcode
-  - [ ] Replace all string references
-  - [ ] Replace URLs (opencode.ai → toothfairyai.com)
-  - [ ] Replace logos and branding assets
-  - [ ] Update package name to `tfcode`
- [x] Create new config schema (`tfcode.json`)
- [ ] Add opencode.json → tfcode.json migration
+- [x] Merge opencode codebase from mirror
+- [x] Apply minimal tfcode branding
+  - [x] Rename `packages/opencode` → `packages/tfcode`
+  - [x] Rename binary `opencode` → `tfcode`
+  - [x] Rename config directory `.opencode/` → `.tfcode/`
+  - [x] Update package.json name to `tfcode`
+  - [x] Update config path references
+  - [x] Keep internal code as "opencode" for easy upstream merges
+- [x] Create tfcode.json schema
 - [x] Define tool type schema
  - [x] `isMCPServer` detection
  - [x] `isAgentSkill` detection
  - [x] `isDatabaseScript` detection
  - [x] `requestType` enum handling
- [x] Implement credential validation
+- [x] Implement credential validation (in tf-sync)
 - [x] Create TF SDK integration layer
 - [x] Multi-region support (AU, EU, US)
+- [x] Document fork management strategy
+- [x] Push to development branch

-### Phase 2: Tool Sync ⏳ IN PROGRESS
+### Phase 2: Tool Sync ⏳ NEXT

 **Tasks**:
- [x] Implement TF workspace tool listing via SDK
- [x] Build tool type classifier
-  - [x] `isMCPServer` detection
-  - [x] `isAgentSkill` detection
-  - [x] `isDatabaseScript` detection
-  - [x] `requestType` enum handling
- [x] Create tool metadata sync using SDK
- [ ] Handle API functions with user credentials
-  - [ ] `isAgentSkill` detection
-  - [ ] `isDatabaseScript` detection
-  - [ ] `requestType` enum handling
- [ ] Create tool metadata sync
+- [ ] Complete tf-sync Python module
+  - [ ] Test tool sync with real TF workspace
+  - [ ] Handle tool metadata caching
+- [ ] Build tf-mcp-bridge TypeScript module
+  - [ ] Bridge between tf-sync and tfcode core
+  - [ ] MCP proxy client implementation
 - [ ] Handle API functions with user credentials
+- [ ] Implement tool refresh/reload

 ### Phase 3: TF Proxy Integration

@ -344,6 +409,9 @@ tfcode tools test <name>           # Test tool call

 **Tasks**:
 - [ ] Implement tfcode CLI commands
+  - [ ] `tfcode validate`
+  - [ ] `tfcode sync`
+  - [ ] `tfcode tools list`
 - [ ] Build interactive credential setup
 - [ ] Add tool status reporting
 - [ ] Create user-friendly error messages
@ -359,73 +427,79 @@ tfcode tools test <name>           # Test tool call

 ---

-## Rebrand Checklist
+## Upstream Sync Process

-### Code References
- [ ] `opencode` → `tfcode` in all source files
- [ ] `OPENCODE_` → `TFCODE_` in environment variables
- [ ] `opencode.json` support (migration) + `tfcode.json` (primary)
- [ ] Package name: `tfcode` (npm, pip)
+When a new opencode release is available:

-### URLs & Branding
- [ ] `opencode.ai` → `toothfairyai.com`
- [ ] `github.com/anomalyco/opencode` → new repo
- [ ] Logo replacement
- [ ] Theme colors (toothfairyai palette)
- [ ] Command: `opencode` → `tfcode`
+1. **Fetch from mirror**
+   ```bash
+   git fetch mirror
+   ```

-### Config
- [ ] Schema URL: `toothfairyai.com/schemas/tfcode.json`
- [ ] Config directory: `~/.config/tfcode/`
- [ ] Data directory: `~/.local/share/tfcode/`
- [ ] Support `opencode.json` for migration
+2. **Merge into development**
+   ```bash
+   git merge mirror/dev
+   ```
+
+3. **Resolve any conflicts**
+   - Should be minimal due to minimal branding approach
+   - Only directory names and config paths differ
+
+4. **Verify branding**
+   ```bash
+   ./scripts/rebrand.sh --check
+   ```
+
+5. **Push to origin**
+   ```bash
+   git push origin development
+   ```

 ---

 ## Implementation Notes

-### 2026-03-24: Planning & Phase 1 Start
+### 2026-03-24: Foundation Complete

-**Product Decision**:
- **Name**: tfcode
- **Positioning**: ToothFairyAI's official coding agent
- **Target**: Existing TF customers
- **Config**: tfcode.json primary, opencode.json supported for migration
+**Key Decisions**:

-**Fork Management**:
- **Upstream**: `github.com/anomalyco/opencode`
- **Mirror**: `gitea.toothfairyai.com/GitHub/opencode` (auto-synced)
- **Development**: `gitea.toothfairyai.com/ToothFairyAI/tf_code` (this repo)
- **Sync Strategy**: Per-release manual PR-based sync
- **Rebrand Script**: `scripts/rebrand.sh` reapplies branding after merges
+1. **Minimal Branding Strategy**
+   - Initially tried bulk rename (1141 files modified)
+   - Realized this would cause massive merge conflicts
+   - Reverted to minimal branding (608 files, mostly renames)
+   - Only changed user-facing surfaces, kept internal code as "opencode"
+   - Result: Clean upstream merges

-**Scope**:
- Full rebrand of codebase
- Tool integration: MCP, Skills, Database, API Functions
- Credentials: TF Proxy for secure types, user-provided for API functions
+2. **Fork Architecture**
+   - Upstream: `github.com/anomalyco/opencode`
+   - Mirror: `gitea.toothfairyai.com/GitHub/opencode` (auto-synced)
+   - Development: `gitea.toothfairyai.com/ToothFairyAI/tf_code`

-**Architecture**: 
- Core engine (TUI, agents, file ops)
- TF integration layer (tool sync, proxy routing)
+3. **Tool Integration Approach**
+   - Use official ToothFairyAI Python SDK
+   - MCP/Skills/DB tools: Credentials stay in TF, route via TF Proxy
+   - API Functions: User provides credentials in config

-**Implementation Progress**:
- [x] README created as living document
- [x] tfcode.json schema defined
- [x] Project structure created (packages/tf-sync, packages/tf-mcp-bridge)
- [x] Python SDK integration (using toothfairyai SDK for multi-region support)
- [x] Tool sync module using SDK's agent_functions.list()
- [x] Multi-region URL configuration (AU, EU, US)
- [x] Fork management strategy documented (FORK_MANAGEMENT.md)
- [x] Rebrand script created (scripts/rebrand.sh)
- [ ] TypeScript/Node.js bridge module
- [ ] MCP proxy client
- [ ] CLI commands
+**Current State**:
+```
+a8b73fd75 refactor: apply minimal tfcode branding
+8bcbd40e9 merge: initial merge from opencode mirror
+abdfa7330 feat: initialize tfcode project structure
+```

-**Key Technical Decisions**:
- Use official ToothFairyAI Python SDK for all TF API interactions
- Multi-region support via Region enum and REGION_URLS config
- Tool types classified by: `isMCPServer`, `isAgentSkill`, `isDatabaseScript`, `requestType`
- Sync functions are synchronous (SDK handles async internally)
+**What's Ready**:
+- ✅ Clean codebase with minimal branding
+- ✅ TF SDK integration layer (Python)
+- ✅ Tool sync module structure
+- ✅ Multi-region support
+- ✅ Config schema defined
+- ✅ Documentation structure
+
+**What's Next**:
+- Complete tf-sync Python module
+- Build tf-mcp-bridge TypeScript module
+- Test with real TF workspace
+- Implement CLI commands

 ---

@ -436,6 +510,10 @@ tfcode tools test <name>           # Test tool call
 - [API Documentation](https://apidocs.toothfairyai.com)
 - [Functions/Tools](https://docs.toothfairyai.com/docs/Settings/functions)

+### OpenCode (Upstream)
+- [GitHub](https://github.com/anomalyco/opencode)
+- [Website](https://opencode.ai)
+
 ### Downloads
 - [tfcode CLI](https://toothfairyai.com/install/tfcode)
 - [npm package](https://www.npmjs.com/package/tfcode)
@ -443,6 +521,14 @@ tfcode tools test <name>           # Test tool call

 ---

+## Credits
+
+tfcode is based on [opencode](https://github.com/anomalyco/opencode) by [anomalyco](https://github.com/anomalyco). 
+
+We thank the opencode team for creating an excellent AI coding tool and for making it open source.
+
+---
+
 ## License

 MIT License