Workspace Structure

What gets pulled

A bundle is written into your workspace (the directory where you ran the pull command), including a safe-merged .claude/mcp.json for MCP servers. Here is the full artifact list:

• Thin agent adapters — CLAUDE.md, AGENTS.md, GEMINI.md — that route your assistant into docs/okf/, written to project root
• docs/okf/ — the OKF knowledge tree (architecture, rules, decisions, context): the single source of truth, written to your workspace
• .env — environment variable template; skipped if a .env already exists
• A minimal scaffold — config, boilerplate, and directories aligned to your locked stack
• manifest.json — the bundle routing manifest; kept in project root for reference and repackage
• resolution_log.json — written by the CLI after pull; records every file written and every conflict resolved
• .claude/mcp.json — MCP server config written to your workspace and safe-merged; global merge is opt-in, never silent

my-saas-app/                 ← your project root (cwd at pull time)
├── docs/
│   └── okf/                 ← OKF knowledge tree — single source of truth
│       ├── protocol.md      ← reading protocol every assistant follows
│       ├── index.md         ← knowledge tree index
│       ├── manifest.json    ← knowledge inventory (versions, hashes)
│       ├── architecture/    ← system.md + one file per locked layer
│       ├── rules/           ← coding.md · architecture.md (· security.md)
│       ├── decisions/       ← adr-001.md … (one ADR per locked decision)
│       └── context/project.md
├── .claude/
│   ├── mcp.json             ← MCP servers (workspace-local, safe-merge)
│   └── agents/              ← subagent adapters
├── CLAUDE.md                ← Claude Code adapter → routes into docs/okf/
├── AGENTS.md                ← AGENTS.md adapter (Codex / OpenCode)
├── GEMINI.md                ← Gemini CLI adapter
├── tasks.md                 ← Build Execution Contract
├── .env                     ← environment template (skip_if_exists)
├── manifest.json            ← bundle routing manifest (kept for reference)
└── resolution_log.json      ← full record of every change made

Files written to your project root

The project root is the current working directory at the time you run logic64 pull. All source code, governance files, and reference artifacts land here.

Files merged into global config

MCP server entries and assistant-level settings are merged into your global assistant config file rather than written as standalone files. The currently supported target is Claude Code CLI.

The global config file path is resolved per platform:

• macOS / Linux: ~/.config/claude-code/config.json
• Windows: %APPDATA%\claude-code\config.json

If the target directory does not exist, the CLI creates it before writing. If no config file is found at the canonical path, the CLI creates a new one and logs a warning in resolution_log.json.

manifest.json

manifest.json is generated by Logic64 and included inside bundle.zip. The CLI rejects any bundle with a missing or malformed manifest. It is the authoritative routing instruction set for a pull.

{
  "version": "3.0",
  "bundle_id": "a3f2bc89-4d1e-47a0-b8c6-2e5f91340abc",
  "project_name": "my-saas-app",
  "generated_at": "2025-05-14T10:32:00Z",
  "target_assistant": "claude",
  "files": [
    {
      "path": "docs/okf/architecture/system.md",
      "destination_type": "workspace_root",
      "merge_strategy": "overwrite"
    },
    {
      "path": "CLAUDE.md",
      "destination_type": "project_root",
      "merge_strategy": "overwrite"
    },
    {
      "path": "tasks.md",
      "destination_type": "project_root",
      "merge_strategy": "overwrite"
    },
    {
      "path": ".claude/mcp.json",
      "destination_type": "workspace_root",
      "merge_strategy": "safe_merge_json"
    },
    {
      "path": ".env.template",
      "destination_type": "env_file",
      "merge_strategy": "skip_if_exists"
    }
  ],
  "env_vars": {
    "PORT": "3000",
    "DB_URL": "placeholder"
  }
}

resolution_log.json

After every logic64 pull, the CLI writes resolution_log.json to your project root. This is your audit trail — every file written, every config entry merged, every conflict auto-resolved, and every backup created is recorded here. There are no silent modifications.

You can review this file any time to understand exactly what Logic64 changed on your machine, and use it as input for logic64 rollback <bundle-id> to undo the pull.

{
  "pulled_at": "2025-05-14T10:33:12Z",
  "bundle_id": "a3f2bc89-4d1e-47a0-b8c6-2e5f91340abc",
  "resolutions": [
    {
      "type": "mcp_name_update",
      "server_name": "logic64-db",
      "config_file": ".claude/mcp.json",
      "action": "updated existing entry"
    },
    {
      "type": "config_backup",
      "original_file": ".claude/mcp.json",
      "backup_file": ".claude/mcp.json.logic64.backup"
    }
  ],
  "files_written": [
    { "destination": "docs/okf/architecture/system.md", "strategy": "overwrite" },
    { "destination": "CLAUDE.md", "strategy": "overwrite" },
    { "destination": "tasks.md", "strategy": "overwrite" },
    { "destination": ".claude/mcp.json", "strategy": "safe_merge_json" }
  ],
  "warnings": []
}

• resolutions[] — one entry per auto-resolved conflict or backup operation (port conflicts, name updates, config backups)
• files_written[] — full list of every file the CLI wrote or merged, with its merge strategy
• warnings[] — non-fatal issues (e.g., config not found at canonical path, fallback path used)

Adapters and the OKF knowledge tree

The governance layer has two parts: thin agent adapters at your project root, and the docs/okf/ knowledge tree in your workspace — both written with an overwrite merge strategy — Logic64 always delivers the authoritative version for the generated workspace.

• CLAUDE.md · AGENTS.md · GEMINI.md — thin adapters for your AI coding assistant: a short constitution that routes it into docs/okf/ and the tasks.md contract. They carry no knowledge of their own — the source of truth lives in the tree.
• docs/okf/ — the knowledge tree: architecture, rules, decisions (ADRs), and context/project.md. Your assistant reads this to understand what was decided and why — preventing it from reinventing choices already locked during the plan phase.

These files are standard Markdown. You may edit them after pulling — they are committed to your project's version control like any other source file. Logic64 will overwrite them again only on the next pull.

MCP server configs

Model Context Protocol servers are written to a single .claude/mcp.json in your workspace and safe-merged there — never a global file. The merge is always atomic and non-destructive.

The safe-merge sequence for .claude/mcp.json:

• Parse the existing config file
• Locate the mcpServers object (keyed by server name)
• If a server with the same name already exists — update its path and port only (this is intentional: same name means the user is updating an existing server)
• If no server with that name exists — append the new server object
• Write back to disk atomically (write to a temporary file, then rename)

The write is always atomic: the CLI writes to a .tmp file first, then renames it over the target. If anything fails mid-write, the original config is left intact and the error is reported — your existing servers are never left in a partial state.

.env handling

Logic64 never overwrites an existing .env file. The merge strategy for the environment template is always skip_if_exists.

• If no .env exists in the project root — the CLI writes the template with placeholder values from the bundle's env_vars map
• If a .env already exists — the CLI skips the write entirely and logs a warning in resolution_log.json. Your existing secrets are never touched.

The template contains only placeholder values (e.g., DB_URL=placeholder). It is designed to be committed to version control as a reference for required environment variables. Fill in real values locally and never commit the populated file.

Backups and rollback

Before the CLI modifies any global config file (files outside your project root), it creates an automatic backup. This gives you a safe rollback path for every pull.

• The backup is created before any merge operation begins — if the merge fails, the original is intact
• Only the most recent pre-pull state is preserved. If a .logic64.backup already exists from a previous pull, it is overwritten
• The backup path is recorded in resolution_log.json under a global_config_backup entry

To restore your machine to the state before a pull:

$ logic64 rollback a3f2bc89-4d1e-47a0-b8c6-2e5f91340abc
# ✓ Restored ~/.config/claude-code/config.json from backup
# ✓ Removed 6 files written to project root
# ✓ rollback_log.json written

• Rollback reads resolution_log.json for the given bundle ID
• For each global_config_backup entry: the backup file is restored over the current config
• For each file written to project_root: the file is deleted (project files are recoverable via version control)
• Rollback writes a rollback_log.json recording all restored and removed files
• Rollback does not perform any git operations

Port and name conflicts

The CLI auto-resolves two classes of conflicts that arise when merging MCP server entries into an existing global config. Both types are logged in resolution_log.json.

Next steps

Now that you understand the full file layout and merge semantics, explore the API that drives bundle delivery, the Studio validation layer, or the complete CLI command reference.