docs: update README with minimal branding insights

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
+- [x] Merge opencode codebase from mirror
-  - [ ] Replace all string references
+- [x] Apply minimal tfcode branding
-  - [ ] Replace URLs (opencode.ai → toothfairyai.com)
+  - [x] Rename `packages/opencode` → `packages/tfcode`
-  - [ ] Replace logos and branding assets
+  - [x] Rename binary `opencode` → `tfcode`
-  - [ ] Update package name to `tfcode`
+  - [x] Rename config directory `.opencode/` → `.tfcode/`
-- [x] Create new config schema (`tfcode.json`)
+  - [x] Update package.json name to `tfcode`
-- [ ] Add opencode.json → tfcode.json migration
+  - [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
+- [ ] Complete tf-sync Python module
-- [x] Build tool type classifier
+  - [ ] Test tool sync with real TF workspace
-  - [x] `isMCPServer` detection
+  - [ ] Handle tool metadata caching
-  - [x] `isAgentSkill` detection
+- [ ] Build tf-mcp-bridge TypeScript module
-  - [x] `isDatabaseScript` detection
+  - [ ] Bridge between tf-sync and tfcode core
-  - [x] `requestType` enum handling
+  - [ ] MCP proxy client implementation
-- [x] Create tool metadata sync using SDK
-- [ ] Handle API functions with user credentials
-  - [ ] `isAgentSkill` detection
-  - [ ] `isDatabaseScript` detection
-  - [ ] `requestType` enum handling
-- [ ] Create tool metadata sync
 - [ ] 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
+When a new opencode release is available:
-- [ ] `opencode` → `tfcode` in all source files
-- [ ] `OPENCODE_` → `TFCODE_` in environment variables
-- [ ] `opencode.json` support (migration) + `tfcode.json` (primary)
-- [ ] Package name: `tfcode` (npm, pip)
 
-### URLs & Branding
+1. **Fetch from mirror**
-- [ ] `opencode.ai` → `toothfairyai.com`
+   ```bash
-- [ ] `github.com/anomalyco/opencode` → new repo
+   git fetch mirror
-- [ ] Logo replacement
+   ```
-- [ ] Theme colors (toothfairyai palette)
-- [ ] Command: `opencode` → `tfcode`
 
-### Config
+2. **Merge into development**
-- [ ] Schema URL: `toothfairyai.com/schemas/tfcode.json`
+   ```bash
-- [ ] Config directory: `~/.config/tfcode/`
+   git merge mirror/dev
-- [ ] Data directory: `~/.local/share/tfcode/`
+   ```
-- [ ] Support `opencode.json` for migration
+
+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**:
+**Key Decisions**:
-- **Name**: tfcode
-- **Positioning**: ToothFairyAI's official coding agent
-- **Target**: Existing TF customers
-- **Config**: tfcode.json primary, opencode.json supported for migration
 
-**Fork Management**:
+1. **Minimal Branding Strategy**
-- **Upstream**: `github.com/anomalyco/opencode`
+   - Initially tried bulk rename (1141 files modified)
-- **Mirror**: `gitea.toothfairyai.com/GitHub/opencode` (auto-synced)
+   - Realized this would cause massive merge conflicts
-- **Development**: `gitea.toothfairyai.com/ToothFairyAI/tf_code` (this repo)
+   - Reverted to minimal branding (608 files, mostly renames)
-- **Sync Strategy**: Per-release manual PR-based sync
+   - Only changed user-facing surfaces, kept internal code as "opencode"
-- **Rebrand Script**: `scripts/rebrand.sh` reapplies branding after merges
+   - Result: Clean upstream merges
 
-**Scope**:
+2. **Fork Architecture**
-- Full rebrand of codebase
+   - Upstream: `github.com/anomalyco/opencode`
-- Tool integration: MCP, Skills, Database, API Functions
+   - Mirror: `gitea.toothfairyai.com/GitHub/opencode` (auto-synced)
-- Credentials: TF Proxy for secure types, user-provided for API functions
+   - Development: `gitea.toothfairyai.com/ToothFairyAI/tf_code`
 
-**Architecture**: 
+3. **Tool Integration Approach**
-- Core engine (TUI, agents, file ops)
+   - Use official ToothFairyAI Python SDK
-- TF integration layer (tool sync, proxy routing)
+   - MCP/Skills/DB tools: Credentials stay in TF, route via TF Proxy
+   - API Functions: User provides credentials in config
 
-**Implementation Progress**:
+**Current State**:
-- [x] README created as living document
+```
-- [x] tfcode.json schema defined
+a8b73fd75 refactor: apply minimal tfcode branding
-- [x] Project structure created (packages/tf-sync, packages/tf-mcp-bridge)
+8bcbd40e9 merge: initial merge from opencode mirror
-- [x] Python SDK integration (using toothfairyai SDK for multi-region support)
+abdfa7330 feat: initialize tfcode project structure
-- [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
 
-**Key Technical Decisions**:
+**What's Ready**:
-- Use official ToothFairyAI Python SDK for all TF API interactions
+- ✅ Clean codebase with minimal branding
-- Multi-region support via Region enum and REGION_URLS config
+- ✅ TF SDK integration layer (Python)
-- Tool types classified by: `isMCPServer`, `isAgentSkill`, `isDatabaseScript`, `requestType`
+- ✅ Tool sync module structure
-- Sync functions are synchronous (SDK handles async internally)
+- ✅ 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