# How the Symlink Layout in text-to-cad Enables Seamless Development

> Learn how the symlink layout in earthtojake/text-to-cad streamlines development. Discover instant code propagation and efficient development workflows. Explore the benefits now.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: internals
- Published: 2026-07-31

---

**The symlink layout in the `develop` branch creates symbolic links from consumer directories like `viewer/packages/` and `plugins/cad/skills/` back to the true source trees in `packages/` and `skills/`, enabling instant code propagation across the entire codebase while ensuring production bundles remain self-contained.**

The `earthtojake/text-to-cad` repository implements a sophisticated **symlink layout** to streamline development workflows for CAD agents. In the `develop` branch, directories such as `viewer/packages/*`, `plugins/cad/skills/*`, and generated runtime paths are not duplicated copies but symbolic links pointing to canonical source locations. This architecture, documented in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md), eliminates file redundancy and ensures that modifications to source files immediately reflect across all consumers including the viewer, plugins, and skill runtimes.

## Core Benefits of the Development Symlink Layout

### Single Source of Truth for All Components

The symlink layout establishes one canonical location for every shared module. Files under `viewer/packages/*` and `plugins/cad/skills/*` are symbolic links to the original code residing in `packages/` or `skills/`. When you edit [`packages/cadjs/src/render.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/render.js), the change is instantly visible to the viewer because `viewer/packages/cadjs` links directly to that directory. This eliminates version drift between copies and reduces maintenance overhead across the monorepo.

### Rapid Iteration with Automated Setup

The repository provides [`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh) to create the entire development layout in a single step. This script orchestrates [`scripts/dev/setup-skill-symlink.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-skill-symlink.sh) for individual skills and [`scripts/dev/setup-plugin-symlink.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-plugin-symlink.sh) for plugin directories, outputting "Development symlink layout is ready." upon completion. Developers can validate the integrity of these links without modifying anything by running the script with the `--check` flag, which ensures no broken links exist before executing tests.

### Guaranteed Production Integrity

While symlinks accelerate development, they never reach production. The bundling pipeline in [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) executes an `assert_no_symlinks` check that fails the build if any symbolic links remain. The bundle process replaces all symlinks with concrete file copies, ensuring that released artifacts are self-contained and portable. This strict separation prevents accidental dependencies on the development filesystem structure.

### Isolated Skills with Shared Resources

Each skill lives independently under `skills/` and is linked into `plugins/cad/skills/` via dedicated symlink scripts. This isolation allows the skill runtime to access shared helpers in `packages/` while keeping skill-specific code separate. Large generated assets, such as CAD meshes stored in `models/`, are referenced through symlinks rather than duplicated across runtimes, keeping the repository lightweight and storage-efficient.

## Working with the Symlink Layout

To establish the development environment, execute the setup script from the repository root:

```bash
scripts/dev/setup-symlinks.sh

```

This command sets up skill symlinks, creates plugin symlinks, and prints confirmation when the layout is ready.

To verify that all symbolic links are intact without modifying the filesystem:

```bash
scripts/dev/setup-symlinks.sh --check

```

If a link is broken, the script returns a specific error indicating which `path/to/link must be a symlink to expected/target`, allowing you to repair the layout before running tests.

When editing code, work directly in the source trees. For example, modifying [`packages/cadjs/src/render.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/render.js) immediately affects any viewer command because `viewer/packages/cadjs` is a symlink to that source directory:

```bash

# Edit the actual source

nano packages/cadjs/src/render.js

# Run viewer tests—the changes are live immediately

npm --prefix viewer run test

```

## Building Production Bundles

When preparing a release, the bundle script ensures no symlinks persist in the final artifact:

```bash
scripts/bundle/bundle.sh

```

During execution, the script validates that all symbolic links have been replaced with physical copies. This guarantees that the production package contains no external dependencies on the development directory structure, creating a clean, reproducible artifact suitable for distribution.

## Summary

- The **symlink layout** establishes a single source of truth by linking `viewer/packages/*` and `plugins/cad/skills/*` to canonical source directories in `packages/` and `skills/`.
- **[`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh)** automates the creation and validation of development links, while **[`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh)** ensures production builds contain only concrete files.
- Editing source files propagates changes instantly to all consumers without file copying, enabling rapid iteration across the viewer and plugins.
- Large assets remain in `models/` and are referenced via symlinks to minimize repository bloat and prevent duplication.
- The `--check` flag validates link integrity, preventing hard-to-debug issues caused by broken symbolic references.

## Frequently Asked Questions

### What happens if a symlink breaks during development?

Running `scripts/dev/setup-symlinks.sh --check` detects broken links immediately and returns a specific error message indicating which path must be a symlink to its expected target. This allows developers to repair the layout before running tests or builds, preventing runtime errors caused by missing dependencies.

### Why does the production build remove all symlinks?

Production bundles must be self-contained and portable across different filesystems. The [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) script explicitly asserts that no symlinks exist using `assert_no_symlinks` and replaces them with physical copies, ensuring the artifact contains all necessary files without external dependencies on the development machine's directory structure.

### How does the symlink layout handle large binary assets like CAD models?

Large generated assets stored in `models/` are never duplicated across runtimes. Instead, components reference the single canonical copy through symlinks, significantly reducing storage requirements and ensuring that all viewers and plugins use identical asset versions without wasting disk space.

### Can I manually create symlinks instead of using the setup script?

While technically possible, manual symlink creation risks path inconsistencies and incomplete coverage. The [`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh) script orchestrates [`setup-skill-symlink.sh`](https://github.com/earthtojake/text-to-cad/blob/main/setup-skill-symlink.sh) and [`setup-plugin-symlink.sh`](https://github.com/earthtojake/text-to-cad/blob/main/setup-plugin-symlink.sh) to ensure correct relative paths and complete layout coverage, making it the recommended and maintained approach according to the repository's [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) guidelines.