Workspace Structure

What gets pulled

A bundle contains two categories of artifacts: files written to your project root (the directory where you ran the pull command), and entries merged into your global assistant config (a single JSON file in your home directory). Here is the full artifact list:

• CLAUDE.md — AI assistant behavioral rules, written verbatim to project root
• memory.md — project context and locked architectural decisions, written to project root
• .env — environment variable template; skipped if a .env already exists
• Source code and directories — the full generated scaffold (files, boilerplate, configs)
• manifest.json — the 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
• MCP server entries — merged safely into your global assistant config (not written as a standalone file to the project)

my-saas-app/               ← your project root (cwd at pull time)
├── src/                   ← generated source code
│   ├── app/
│   ├── components/
│   └── lib/
├── CLAUDE.md              ← AI assistant rules
├── memory.md              ← project context & locked decisions
├── .env                   ← environment template (skip_if_exists)
├── manifest.json          ← 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.

{
  "manifest_version": "1.0",
  "bundle_id": "a3f2bc89-4d1e-47a0-b8c6-2e5f91340abc",
  "project_name": "my-saas-app",
  "generated_at": "2025-05-14T10:32:00Z",
  "target_assistant": "claude",
  "files": [
    {
      "source": "root/CLAUDE.md",
      "destination_type": "project_root",
      "filename": "CLAUDE.md",
      "merge_strategy": "overwrite"
    },
    {
      "source": "root/memory.md",
      "destination_type": "project_root",
      "filename": "memory.md",
      "merge_strategy": "overwrite"
    },
    {
      "source": "root/.env.template",
      "destination_type": "env_file",
      "filename": ".env",
      "merge_strategy": "skip_if_exists"
    },
    {
      "source": "config/mcp.json",
      "destination_type": "global_config",
      "filename": "config.json",
      "merge_strategy": "safe_merge_json"
    }
  ],
  "mcp_servers": [
    {
      "name": "logic64-db",
      "port": 3100,
      "config_path": "mcp/db-server.json"
    }
  ],
  "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": "port_conflict",
      "original_port": 3100,
      "resolved_port": 3101,
      "config_file": "~/.config/claude-code/config.json"
    },
    {
      "type": "mcp_name_update",
      "server_name": "logic64-db",
      "action": "updated existing entry"
    },
    {
      "type": "global_config_backup",
      "original_file": "~/.config/claude-code/config.json",
      "backup_file": "~/.config/claude-code/config.json.logic64.backup"
    }
  ],
  "files_written": [
    { "destination": "/project-root/CLAUDE.md", "strategy": "overwrite" },
    { "destination": "/project-root/memory.md", "strategy": "overwrite" },
    { "destination": "/project-root/manifest.json", "strategy": "overwrite" },
    { "destination": "/project-root/resolution_log.json", "strategy": "overwrite" },
    { "destination": "~/.config/claude-code/config.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)

CLAUDE.md and memory.md

These two files are the governance layer that Logic64 installs alongside your source code. They are written verbatim from the bundle to your project root with an overwrite merge strategy — Logic64 always delivers the authoritative version for the generated workspace.

• CLAUDE.md — behavioral rules for your AI coding assistant: how to debug, code standards, development commands, and which documentation files govern which features. When your assistant reads this file, it operates within the constraints Logic64 established during generation.
• memory.md — project context, locked architectural decisions, and their rationale. Your assistant reads this to understand what was decided and why — preventing it from reinventing choices already made during the plan phase.

Both 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 server entries are merged into your global assistant config file rather than written as standalone files. The merge is always atomic and non-destructive.

The merge sequence for each MCP entry in manifest.json:

• Parse the existing config file
• Locate the MCP servers array
• 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.