# Contributing to Axint

Thanks for considering a contribution to Axint. This guide will get you oriented quickly.

## Before You Start

1. **Open an issue first for large changes.** Bug fixes and new templates can go straight to a PR. But if you're changing the compiler, validator, type system, or MCP server architecture, open an issue or discussion first so we can align on the approach before you invest time.

2. **Check existing issues.** Browse [open issues](https://github.com/agenticempire/axint/issues) — especially those labeled `good first issue` — to find work that's ready to pick up.

## Architecture Overview

Understanding the project structure will save you time. Axint is no longer only
a TypeScript-to-Swift compiler; the repo also contains the repair loop, MCP
surface, project memory, Xcode proof path, telemetry controls, and starter
generation that make the compiler useful to agents.

```
src/
├── core/
│   ├── parser.ts        # Extracts defineIntent() calls → IR
│   ├── view-parser.ts   # SwiftUI view parser
│   ├── widget-parser.ts # WidgetKit parser
│   ├── app-parser.ts    # SwiftUI app scaffold parser
│   ├── generator.ts     # Transforms IR → Swift source
│   ├── swift-validator.ts # Existing Swift repair/diagnostic rules
│   ├── compiler.ts      # Orchestrates the full compile pipeline
│   ├── types.ts         # IR types, Swift type mappings, diagnostics
│   └── index.ts         # Barrel export
├── sdk/
│   └── index.ts         # define*() APIs and helpers (exported from `@axint/compiler`)
├── mcp/
│   ├── server.ts        # MCP server with axint.* tools and built-in prompts
│   ├── manifest.ts      # Runtime marketplace/tool description surface
│   ├── index.ts         # Import surface and direct stdio entry point
│   └── register.ts      # axint-mcp binary entry point
├── templates/
│   └── index.ts         # Intent template registry (templates welcome!)
└── cli/
    └── index.ts         # CLI entry: create, compile, validate, repair, run, xcode
```

**Key data flow:**

```
TypeScript / Python / JSON / .axint definition
        ↓
   parser or schema lowering → Intermediate Representation (IR)
        ↓
   validator           → checks Apple API constraints
        ↓
   generator           → emits Swift, plist, and entitlements
        ↓
   Swift validator     → catches build-time Apple and SwiftUI failures
        ↓
   Fix Packet / Run proof / MCP response
```

## What We're Looking For

### Always Welcome (just open a PR)

- **New intent templates** — Calendar, reminders, messaging, media playback, smart home, health, maps, payments. Each template in `src/templates/` follows a consistent pattern. Look at an existing one and add yours.
- **Existing-product repair fixtures** — Small SwiftUI/Xcode examples where Axint should diagnose a real failure such as blocked taps, scroll regressions, missing imports, bad bindings, or concurrency issues.
- **Documentation** — Better explanations, more examples, typo fixes.
- **Bug fixes** — Especially with a failing test that demonstrates the issue.
- **Test coverage** — We can always use more tests, particularly for edge cases in the compiler and validator.

### Welcome With Prior Discussion (open an issue first)

- **New MCP tools** — Additional tools exposed through the MCP server.
- **Compiler changes** — Modifications to the TypeScript/Python/JSON/`.axint` → IR → Swift pipeline.
- **New target surfaces** — Support for SiriKit, Shortcuts, or other Apple execution surfaces beyond App Intents.
- **Dependency additions** — Any new runtime dependency needs justification.

### Out of Scope for This Repo

The open-source repository is for the compiler, SDKs, CLI, MCP server, templates, tests, and editor integrations.

Please do not open PRs that add private product materials or internal operating docs here, such as:

- Launch copy or GTM assets
- Private website or registry implementation details
- Hosted service playbooks or commercial planning docs
- Internal analytics, sales, or partnership materials
- Local-machine paths, internal agent instructions, or private implementation plans

## Development Setup

```bash
# Clone the repo
git clone https://github.com/agenticempire/axint.git
cd axint

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Run the CLI locally
npm run dev -- compile examples/calendar-assistant.ts --stdout
```

## Fastest first contribution path

If you want the cleanest first PR:

1. Pick a small bug, doc fix, template improvement, or validator edge case.
2. Reproduce it with the smallest possible fixture in `tests/`.
3. Make the code change in the matching `src/` area.
4. Run the narrowest checks first, then the repo-wide gates:

```bash
npm run typecheck
npm run lint
npm run build
npm run metrics:check
npm test
```

Good “first contribution” categories:

- small validator or generator bug fixes
- additional tests for real edge cases
- template improvements
- doc corrections
- Xcode workflow polish

## Pull Request Process

1. **Fork and branch.** Create a feature branch from `main`. Use a descriptive name: `feat/smart-home-template`, `fix/parameter-type-marshaling`, `docs/mcp-setup-guide`.

2. **Write tests.** New features need tests. Bug fixes need a test that would have caught the bug. Tests live in `tests/` mirroring the `src/` structure.

3. **Follow existing patterns.** Match the code style you see in the repo. We use Prettier for formatting and ESLint for linting:
   ```bash
   npm run lint
   npm run format
   ```

4. **Keep PRs focused.** One feature or fix per PR. If you find an unrelated issue while working, open a separate PR for it.

5. **Write a clear PR description.** Explain what changed and why. If it's a template, show an example of the TypeScript input and Swift output.

6. **CI must pass.** All tests, linting, and type checks must pass before merge.

## Release process

Releases should feel boring and reproducible.

Use this checklist:

1. Sync versions and metrics:

```bash
npm run versions:check
npm run metrics:check
```

2. Run the core repo gates:

```bash
npm run typecheck
npm run lint
npm run build
npm test
```

3. If Xcode repair rules changed, confirm the checked-in fixer is current:

```bash
npm run gen:swift-fixer:check
```

4. If docs or public proof changed, update:
   - `README.md`
   - `docs/ERRORS.md`
   - `docs/COVERAGE.md`
   - `docs/RELEASE_NOTES.md`

5. If headline numbers or public proof changed, sync the downstream public surfaces that read from the truth bundle before announcing the release.

6. Keep package releases aligned.
   Intentional releases now require npm and PyPI to move together. The release workflow:
   - requires `PYPI_TOKEN`
   - verifies both registries are in sync before publish
   - verifies both registries are live after publish

   You can run the same guard locally with:

   ```bash
   npm run release:check
   ```

7. Only tag and publish once the repo state, docs, metrics, and downstream public proof all agree.

## Adding a New Template

Templates are the easiest way to contribute. Here's the pattern:

```typescript
// src/templates/your-template.ts
import type { IntentTemplate } from "../templates/index";

export const yourTemplate: IntentTemplate = {
  id: "your-template",
  name: "Your Template Name",
  description: "What this template does",
  category: "productivity", // e.g., "productivity", "media", "smart-home"
  source: `
import { defineIntent, param } from "@axint/compiler";

export default defineIntent({
  name: "YourIntent",
  title: "Your Intent Title",
  description: "What this intent does",
  params: {
    // Define parameters here
  },
  perform: async (params) => {
    return { success: true };
  },
});
  `.trim(),
};
```

Then register it in `src/templates/index.ts` by adding it to the `templates` array.

## Code of Conduct

Be respectful. Be constructive. We're building something together. Toxic behavior, harassment, and bad-faith engagement will result in removal from the project.

## Questions?

- **GitHub Discussions** — For architecture questions and ideas
- **GitHub Issues** — For bugs, regressions, and feature requests

---

Thanks for helping Apple coding agents produce work that can be checked, repaired, and proved.