Skip to content

Comprehensive Documentation Audit and Update #192

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yacosta738 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Comprehensive Documentation Audit and Update #192

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion .agents/journal/scribe-journal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,18 @@ This journal is used to track documentation debt and planned improvements for th
- [x] Add a "Troubleshooting" section to the root `README.md`.
- [x] Reconcile CLI documentation with actual source code.
- [x] Document missing `skill` and `clean` commands.
- [ ] Add more detailed examples to the Starlight documentation.
- [x] Add more detailed examples to the Starlight documentation.
- [ ] Create a "Recipes" section in the Starlight documentation for common use cases.
- [x] Document `doctor` and `status` commands in `cli.mdx`.
- [x] Create `.agents/AGENTS.md` as the single source of truth.
- [x] Add project overview and mono-repo structure to root `README.md`.
- [x] Document all build, lint, test, and release commands in root `README.md`.

## Planned Improvements

- [x] Improve `getting-started.mdx` with Node.js package manager installation.
- [x] Document mono-repo structure and cross-stack workflow in `contributing.mdx` and `workspaces.mdx`.
- [x] Fix download instructions with version placeholders in docs.
- [ ] Create a more comprehensive guide to the `agentsync.toml` configuration file.
- [ ] Add a guide for creating custom `agentsync` agents.
- [ ] Create a video tutorial for getting started with `agentsync`.
5 changes: 3 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,9 @@ Thank you for your interest in contributing to AgentSync! To maintain high code
- If it's documentation, it goes in `website/docs/src/content/docs/`.
3. **Verify your changes**:
- **Full Suite**: Run `make verify-all` from the root. This runs all tests, linters, and builds the documentation.
- For Rust: `make rust-test`, `cargo fmt`, and `cargo clippy`.
- For TypeScript: `make js-test`, `make js-build` and `make fmt`.
- For Rust: `make rust-test`, `make rust-build`, and `cargo clippy`.
- For TypeScript: `make js-test` and `make js-build`.
- Formatting: `make fmt` (formats both Rust and TypeScript).
Comment on lines +14 to +16
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Minor inconsistency: cargo fmt vs make fmt in the same file

Line 16 directs contributors to use make fmt, but line 27 (Code Style › Rust) still says "Use cargo fmt before committing." Since make fmt wraps cargo fmt, both are correct, but the duplicate guidance can confuse new contributors about which invocation to prefer. Consider aligning line 27 to match the monorepo-preferred make fmt.

♻️ Suggested alignment 
-Use `cargo fmt` before committing.
+Use `make fmt` (or `cargo fmt` directly) before committing.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CONTRIBUTING.md` around lines 14 - 16, Update the Rust code style guidance so
both places recommend the monorepo wrapper: replace the standalone "Use `cargo
fmt` before committing." (under "Code Style › Rust") with guidance to run the
repository formatter (e.g., "Use `make fmt` which wraps `cargo fmt`") and
optionally note that `cargo fmt` is invoked by `make fmt`; ensure the text
references the same phrasing "make fmt" as used earlier to avoid inconsistency.

4. **Open a Pull Request** with a clear description of the changes and why they are needed.

## Code Style
Expand Down
92 changes: 48 additions & 44 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,7 @@ agentsync doctor [--project-root <path>]
agentsync skill install <skill-id>
agentsync skill update <skill-id>
agentsync skill uninstall <skill-id>
# agentsync skill list (Currently under development)
```

### Status
Expand Down Expand Up @@ -435,62 +436,65 @@ If you need agentsync in CI, you can download the latest version automatically u

## Getting Started (Development)

This project is a monorepo containing a Rust core and a JavaScript/TypeScript wrapper.
This project is a monorepo containing a Rust core and a JavaScript/TypeScript distribution layer.

### Repository Structure
### Monorepo Structure

- `src/`: Core logic and CLI implementation in **Rust**.
- `npm/agentsync/`: **TypeScript** wrapper used for NPM distribution.
- `website/docs/`: Documentation site built with **Starlight**.
- `tests/`: Integration tests for the CLI.
- `.agents/`: Single source of truth for agent configurations and skills.
- `tests/`: Integration and E2E tests for the CLI.

### Prerequisites

- [**Rust**](https://www.rust-lang.org/tools/install) (1.89+ recommended)
- [**Node.js**](https://nodejs.org/) (v24.13.0+ recommended for development)
- [**Rust**](https://www.rust-lang.org/tools/install) (1.89+ recommended, Edition 2024)
- [**Node.js**](https://nodejs.org/) (v24.13.0+ recommended)
Comment on lines +451 to +452
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Overly specific Node.js patch-version constraint

v24.13.0+ is unusually precise for a prerequisite. Documenting a patch version as the floor means users on v24.14.0 or any later patch may wonder if that's intentional or a copy-paste of a engines field. A minor-version floor (v24) is the conventional form unless the specific patch version is materially required.

♻️ Suggested wording 
-- [**Node.js**](https://nodejs.org/) (v24.13.0+ recommended)
+- [**Node.js**](https://nodejs.org/) (v24+ recommended)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- [**Rust**](https://www.rust-lang.org/tools/install) (1.89+ recommended, Edition 2024)
- [**Node.js**](https://nodejs.org/) (v24.13.0+ recommended)
- [**Rust**](https://www.rust-lang.org/tools/install) (1.89+ recommended, Edition 2024)
- [**Node.js**](https://nodejs.org/) (v24+ recommended)
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 451 - 452, The README currently pins Node.js to a
specific patch floor in the list entry '- [**Node.js**](https://nodejs.org/)
(v24.13.0+ recommended)'; update this to use a minor-version floor instead
(e.g., change the text to '(v24+ recommended)' or '(v24 recommended)') so it
doesn't imply an unnecessary patch-level constraint—modify the Node.js line in
the README accordingly.

- [**pnpm**](https://pnpm.io/installation)

### Setup

1. **Install JavaScript dependencies:**

```bash
pnpm install
```

2. **Build the Rust binary:**

```bash
cargo build
```

### Common Commands

This project uses a `Makefile` to orchestrate common tasks.

- **Run Rust tests:**

```bash
make rust-test
```

- **Run JavaScript tests:**

```bash
make js-test
```

- **Build all components:**

```bash
make all
```

- **Format the code:**

```bash
make fmt
```
1. **Clone the repository**:
```bash
git clone https://github.com/dallay/agentsync.git
cd agentsync
```

2. **Install all dependencies**:
```bash
make install
# This runs pnpm install and cargo build
```

### Development Workflow

#### Rust (Core)
- **Build**: `make rust-build` (or `cargo build`)
- **Test**: `make rust-test` (or `cargo test`)
- **Run**: `make rust-run` (or `cargo run -- <args>`)
- **Lint**: `cargo clippy`

#### JavaScript / TypeScript (Wrapper & Docs)
- **Build**: `make js-build` (builds the `@dallay/agentsync` package)
- **Test**: `make js-test` (runs type checks and tests)
- **Docs (Dev)**: `make docs-dev` (starts Starlight dev server)

### Common Commands (Makefile)

We use a `Makefile` to orchestrate tasks across both stacks:

| Command | Description |
| :--- | :--- |
| `make all` | Install dependencies and build all components |
| `make verify-all` | **Recommended before PRs**: Runs all builds, tests, and linters |
| `make install` | Install JS dependencies and build Rust core |
| `make fmt` | Format both Rust (rustfmt) and JS/TS (biome) |
| `make rust-test` | Run all Rust unit and integration tests |
| `make rust-run` | Build and run the Rust CLI project |
| `make js-test` | Run all JavaScript tests and type checks |
| `make e2e-test` | Run end-to-end tests using Docker |
| `make docs-build` | Build the documentation site |
| `make clean` | Remove build artifacts and temporary files |

## Troubleshooting

Expand Down
63 changes: 33 additions & 30 deletions npm/agentsync/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,18 @@ Remove previously created symbolic links:
agentsync clean
```

#### Status and Diagnostics:

Check the status of managed symlinks or run a diagnostic health check:

```bash
# Verify the state of symlinks and report drift
agentsync status

# Run a comprehensive diagnostic and health check
agentsync doctor
```

🎯 **Example Workflows**:

- **Programmatic Usage in Node.js**:
Expand Down Expand Up @@ -107,56 +119,47 @@ agentsync clean
## MCP & Skills

- AgentSync supports MCP generation for multiple agents (Claude, Copilot, Gemini, Cursor, VS Code, OpenCode). The canonical list and file locations live in the repo README and in the docs site (guides/mcp).
- Skills live under `.agents/skills/` in the project.
- Skills live under `.agents/skills/` in the project.
- **Manage skills via CLI**:
```bash
agentsync skill install <skill-id>
agentsync skill update <skill-id>
agentsync skill uninstall <skill-id>
```
Comment on lines +122 to +128
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check for uninstall command in Rust source
rg -n --type=rust -C3 'uninstall'

Repository: dallay/agentsync

Length of output: 9052

🏁 Script executed:

# Find and check cli.mdx for skill documentation
fd -type f -name 'cli.mdx' -o -name 'cli.md'

Repository: dallay/agentsync

Length of output: 230

🏁 Script executed:

# Get a broader view of the project structure
find . -type f -name '*.mdx' | head -20

Repository: dallay/agentsync

Length of output: 480

🏁 Script executed:

cat -n ./website/docs/src/content/docs/reference/cli.mdx

Repository: dallay/agentsync

Length of output: 8576

Add uninstall subsection to cli.mdx under the skill command section

The agentsync skill uninstall command is fully implemented in the Rust codebase, but it's missing from the CLI reference documentation. cli.mdx documents install and update subcommands (lines 102–122) and list (lines 124–137), but has no entry for uninstall. Add a corresponding subsection alongside install and update to keep documentation in sync with the implemented functionality.

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 124-124: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@npm/agentsync/README.md` around lines 122 - 128, Add a new "uninstall"
subsection to the skill command docs in cli.mdx mirroring the style of the
existing "install" and "update" sections: describe the command usage `agentsync
skill uninstall <skill-id>`, explain what it does, list any flags/behavior, and
include a short example of uninstalling a skill; ensure the subsection appears
alongside the existing install/update sections so the CLI reference includes the
implemented `agentsync skill uninstall` command.

Comment on lines +123 to +128
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

MD031 — fenced code blocks missing surrounding blank lines (3 instances)

Static analysis (markdownlint MD031) flags lines 124, 147, and 152 for missing blank lines around fenced code blocks. All three occur directly beneath a list-item label line.

♻️ Proposed fix for all three occurrences 
 - **Manage skills via CLI**:
+
   ```bash
   agentsync skill install <skill-id>
   agentsync skill update <skill-id>
   agentsync skill uninstall <skill-id>

```diff
 1. **Install dependencies and build core**:
+
    ```bash
    make install
    ```
+
 2. **Build the NPM package**:
+
    ```bash
    make js-build
    ```

Also applies to: 146-154

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 124-124: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@npm/agentsync/README.md` around lines 123 - 128, Add a blank line before each
fenced code block that immediately follows a list-item label to satisfy MD031:
for the three occurrences under the list labels (the "Manage skills via CLI"
block with the three agentsync commands and the two blocks in the NPM
package/build section), insert a single empty line between the list-item line
and the opening ```bash so each fenced code block is surrounded by blank lines.


---

## 👷 Development

This package is part of the [AgentSync mono-repo](https://github.com/dallay/agentsync). It serves as a Node.js wrapper for the high-performance Rust core.
This package is part of the [AgentSync mono-repo](https://github.com/dallay/agentsync). It serves as a Node.js distribution layer for the high-performance Rust core.

### Prerequisites

- [pnpm](https://pnpm.io/): Dependency manager.
- [Node.js](https://nodejs.org/) >= 24.13.0 (for development).
- [Rust](https://www.rust-lang.org/): For building the core CLI.

### Steps

1. Clone the repository:
- [**pnpm**](https://pnpm.io/): Dependency manager.
- [**Node.js**](https://nodejs.org/) >= 24.13.0.
- [**Rust**](https://www.rust-lang.org/): For building the core CLI (1.89+).

```bash
git clone https://github.com/dallay/agentsync.git
cd agentsync
```
### Setup and Build

2. Install dependencies:
From the monorepo root:

1. **Install dependencies and build core**:
```bash
pnpm install
make install
```

3. Build:

2. **Build the NPM package**:
```bash
make js-build
# or
pnpm run build
```

4. Run tests and type checks:

```bash
make js-test
# or
pnpm run typecheck
```
### Common Commands

5. Format:
- **Run tests and type checks**: `make js-test`
- **Format code**: `make fmt`
- **Full verification**: `make verify-all`

```bash
make fmt
```
For more details on the Rust core development, see the [main README](https://github.com/dallay/agentsync/blob/main/README.md).

---

Expand Down
7 changes: 4 additions & 3 deletions website/docs/src/content/docs/guides/contributing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Contributing
description: Guidelines for contributing to the agentsync project.
---

Thank you for your interest in contributing to AgentSync. To maintain high code quality and consistency, please follow these guidelines.
Thank you for your interest in contributing to AgentSync! To maintain high code quality and consistency, please follow these guidelines.

## Development Workflow

Expand All @@ -14,8 +14,9 @@ Thank you for your interest in contributing to AgentSync. To maintain high code
- If it's documentation, it goes in `website/docs/src/content/docs/`.
3. **Verify your changes**:
- **Full Suite**: Run `make verify-all` from the root. This runs all tests, linters, and builds the documentation.
- For Rust: `make rust-test`, `cargo fmt`, and `cargo clippy`.
- For TypeScript: `make js-test`, `make js-build` and `make fmt`.
- For Rust: `make rust-test`, `make rust-build`, and `cargo clippy`.
- For TypeScript: `make js-test` and `make js-build`.
- Formatting: `make fmt` (formats both Rust and TypeScript).
4. **Open a Pull Request** with a clear description of the changes and why they are needed.

## Code Style
Expand Down
14 changes: 9 additions & 5 deletions website/docs/src/content/docs/guides/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,21 +57,25 @@ bunx @dallay/agentsync apply

### From GitHub Releases

Download the latest release for your platform:
Download the latest release for your platform from the [GitHub Releases](https://github.com/dallay/agentsync/releases) page.

> **Note:** In the examples below, replace `<version>` with the actual version tag you wish to download (e.g., `1.28.0`).

#### macOS (Apple Silicon)

```bash
curl -LO https://github.com/dallay/agentsync/releases/latest/download/agentsync-aarch64-apple-darwin.tar.gz
tar xzf agentsync-aarch64-apple-darwin.tar.gz
# Replace <version> with the actual version number
curl -LO https://github.com/dallay/agentsync/releases/download/v<version>/agentsync-<version>-aarch64-apple-darwin.tar.gz
tar xzf agentsync-<version>-aarch64-apple-darwin.tar.gz
Comment on lines +67 to +69
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Quote URLs and filenames containing the <version> placeholder to avoid shell metacharacter misinterpretation.

< and > are stdin/stdout redirection operators in bash. Both curl -LO <url> and tar xzf <filename> snippets contain them unquoted. A copy-paste without substitution silently redirects I/O instead of producing a clear "replace the placeholder" error; quoting is also a general best practice for URLs in shell scripts.

📝 Proposed fix — macOS and Linux snippets 
-curl -LO https://github.com/dallay/agentsync/releases/download/v<version>/agentsync-<version>-aarch64-apple-darwin.tar.gz
-tar xzf agentsync-<version>-aarch64-apple-darwin.tar.gz
+curl -LO "https://github.com/dallay/agentsync/releases/download/v<version>/agentsync-<version>-aarch64-apple-darwin.tar.gz"
+tar xzf "agentsync-<version>-aarch64-apple-darwin.tar.gz"
-curl -LO https://github.com/dallay/agentsync/releases/download/v<version>/agentsync-<version>-x86_64-unknown-linux-gnu.tar.gz
-tar xzf agentsync-<version>-x86_64-unknown-linux-gnu.tar.gz
+curl -LO "https://github.com/dallay/agentsync/releases/download/v<version>/agentsync-<version>-x86_64-unknown-linux-gnu.tar.gz"
+tar xzf "agentsync-<version>-x86_64-unknown-linux-gnu.tar.gz"

Also applies to: 76-78

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@website/docs/src/content/docs/guides/getting-started.mdx` around lines 67 -
69, The curl and tar examples use the raw <version> placeholder unquoted, which
can be interpreted as shell redirection; update the curl -LO invocation and the
tar xzf invocation to wrap the URL and the generated filename in quotes so shell
metacharacters aren’t processed (e.g., quote the URL containing v<version> and
the filename pattern agentsync-<version>-aarch64-apple-darwin.tar.gz); apply the
same quoting to the other platform snippet(s) that use agentsync-<version>-...
(the Linux/macos variations) so all instances of curl -LO and tar xzf
referencing <version> are quoted.

sudo mv agentsync-*/agentsync /usr/local/bin/
```

#### Linux (x86_64)

```bash
curl -LO https://github.com/dallay/agentsync/releases/latest/download/agentsync-x86_64-unknown-linux-gnu.tar.gz
tar xzf agentsync-x86_64-unknown-linux-gnu.tar.gz
# Replace <version> with the actual version number
curl -LO https://github.com/dallay/agentsync/releases/download/v<version>/agentsync-<version>-x86_64-unknown-linux-gnu.tar.gz
tar xzf agentsync-<version>-x86_64-unknown-linux-gnu.tar.gz
sudo mv agentsync-*/agentsync /usr/local/bin/
```

Expand Down
6 changes: 3 additions & 3 deletions website/docs/src/content/docs/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,9 @@ import { Code } from '@astrojs/starlight/components';

## Quick Start

<Code code={`# Install (macOS)
curl -LO https://github.com/dallay/agentsync/releases/latest/download/agentsync-aarch64-apple-darwin.tar.gz
tar xzf agentsync-aarch64-apple-darwin.tar.gz
<Code code={`# Install (macOS). Replace <version> with the actual version (e.g., 1.28.0)
curl -LO https://github.com/dallay/agentsync/releases/download/v<version>/agentsync-<version>-aarch64-apple-darwin.tar.gz
tar xzf agentsync-<version>-aarch64-apple-darwin.tar.gz
sudo mv agentsync-*/agentsync /usr/local/bin/

# Initialize and apply
Expand Down
38 changes: 30 additions & 8 deletions website/docs/src/content/docs/reference/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,14 +191,36 @@ Human-friendly output uses colors and statuses:
- `! Missing` — destination does not exist
- `· Exists but not a symlink` — a regular file or directory exists at the destination

Exit codes
Exit codes:
- `0` — no problems detected
- `1` — one or more issues found (suitable to fail CI builds)
Comment on lines +194 to 196
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Inconsistent exit-code heading style between status and doctor

status uses a plain-text label (Exit codes:) while doctor uses bold (**Exit codes**:). Normalise to one style across both sections.

♻️ Proposed fix — align `status` exit codes to bold style 
-Exit codes:
+**Exit codes**:
 - `0` — no problems detected
 - `1` — one or more issues found (suitable to fail CI builds)

Also applies to: 224-226

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@website/docs/src/content/docs/reference/cli.mdx` around lines 194 - 196,
Update the exit-code labels in the docs so both sections use the same bold
style: locate the "status" section's plain-text "Exit codes:" and change it to
"**Exit codes:**", and also update the other occurrence referenced (the "doctor"
section or the lines around the second occurrence) so both sections read "**Exit
codes:**" followed by the code list; ensure the formatting matches the existing
bold style used in the "doctor" section.


Examples
- Human readable:
- `agentsync status`
- JSON for CI:
- `agentsync status --json`
- With custom project root:
- `agentsync status --project-root /path/to/repo --json`
Examples:
- Human readable: `agentsync status`
- JSON for CI: `agentsync status --json`
- With custom project root: `agentsync status --project-root /path/to/repo --json`

---

### `doctor`

Run diagnostic and health checks for the AgentSync environment.

```bash
agentsync doctor [FLAGS]
```

**Flags**:
- `--project-root <PATH>`: Project root directory (defaults to current directory).

**Diagnostics performed**:
1. **Config Loading**: Verifies that `agentsync.toml` can be found and parsed correctly.
2. **Source Directory**: Checks if the configured `source_dir` exists.
3. **Target Sources**: Verifies that all files/directories referenced as `source` in the config actually exist.
4. **Destination Conflicts**: Detects duplicate destinations or overlapping paths (where one destination is a parent of another).
5. **MCP Servers**: Audits configured MCP servers to ensure their `command` executables are available in the system `PATH`.
6. **Gitignore Audit**: Verifies if the `.gitignore` file has the managed AgentSync section and if it is up to date with all required entries.

**Exit codes**:
- `0` — all checks passed
- `1` — one or more issues detected
16 changes: 8 additions & 8 deletions website/docs/src/content/docs/reference/workspaces.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ description: Detailed guide to the repository structure and polyglot development
- `src/`: Core logic and CLI implementation in **Rust**.
- `npm/agentsync/`: **TypeScript** wrapper used for NPM distribution.
- `website/docs/`: Documentation site built with **Starlight**.
- `website/`: Main project website.
- `tests/`: Integration tests for the CLI.
- `.agents/`: Single source of truth for agent configurations and skills.
- `tests/`: Integration and E2E tests for the CLI.

---

Expand All @@ -24,9 +24,9 @@ The core logic is written in Rust for speed, safety, and easy distribution as a
- **Key Commands**:

```bash
cargo build # Build debug binary
cargo test # Run unit and integration tests
cargo run # Run the CLI locally
make rust-build # Build core binary
make rust-test # Run unit and integration tests
make rust-run # Run the CLI locally
```

- **Error Handling**: Uses `thiserror` for custom errors and `anyhow` for application-level error handling.
Expand All @@ -35,15 +35,15 @@ The core logic is written in Rust for speed, safety, and easy distribution as a

## JavaScript Workspace (Distribution)

The JS workspace acts as a wrapper to provide an easy installation path via `pnpm/npm`. It manages platform-specific binary downloads.
The JS workspace provides a Node.js distribution layer and managed binary downloads for different platforms.

- **Tools**: pnpm, TypeScript, Make
- **Location**: `npm/agentsync/`
- **Key Commands**:

```bash
pnpm run typecheck # Verify types
pnpm run build # Compile TypeScript to JS
make js-test # Verify types and run JS tests
make js-build # Compile TypeScript to JS
```

- **Strictness**: We enforce strict TypeScript configurations. Avoid `any` at all costs.
Expand Down
Loading