ai
Activity
Contributors
README
Mountaya AI
Everything public that helps an AI agent build with Mountaya, or contribute to a Mountaya repository:
- Agent skills for the Mountaya products: Map Publishing, Embedded Studio and SDKs & Elements in TypeScript, the Data API, the MCP Server and the Tile API, plus authentication and webhooks.
- The Mountaya MCP server configuration for Claude Code, Cursor, Codex and Gemini CLI.
- Engineering plugins: the conventions Mountaya's public repositories share (TypeScript, Dart, Flutter, Kotlin, Swift) and the tooling policy that goes with them.
- The workspace generator that keeps every Mountaya repository's agent setup identical.
Developer documentation lives at docs.mountaya.com.
This repository lives on Entire, at https://entire.com/et/mountaya/ai. Clone it with
entire repo clone /et/mountaya/ai (the Entire CLI and an
Entire login are needed); <ai-repo> below stands for the path of that checkout.
Agent skills
| Skill | Product | Use it to |
|---|---|---|
mountaya-auth | All | Set up publishable keys, secret keys and session tokens; send and retry writes safely; read rate limits and errors. Every other skill relies on it. |
mountaya-webhooks | All | Receive and verify signed webhook events, handle retries, duplicates and ordering, recover missed events, and find what emits each event. |
mountaya-map-publishing | Map Publishing | Publish a read-only interactive map in an iframe. |
mountaya-sdk-typescript | Embedded Studio, SDKs & Elements | Pick and use the @mountaya/* packages, from the embedded studio to the API client. |
mountaya-data-api | Data API | Compute routes, suggestions, isochrones and matrices; geocode; read terrain; analyze geometry. |
mountaya-mcp | MCP Server | Connect an assistant to the Mountaya MCP Server and choose an authentication mode. |
mountaya-tile-api | Tile API | Add Mountaya terrain, trail and weather layers to a MapLibre GL JS map. |
Skills follow the Agent Skills standard.
Install
Any agent, through the skills CLI:
npx skills add https://docs.mountaya.com # every skill
npx skills add https://docs.mountaya.com --skill mountaya-auth --skill mountaya-data-api
Skills installed this way do not update themselves. Run npx skills update -y to refresh them.
Claude Code, as a plugin that also registers the MCP server:
claude plugin marketplace add <ai-repo>
claude plugin install mountaya@mountaya
Cursor and Codex read .cursor-plugin/marketplace.json and
.codex-plugin/marketplace.json at the root of this repository. Add <ai-repo> as a plugin
source in either tool and install mountaya.
Gemini CLI, the MCP server only:
gemini extensions install <ai-repo>
Keys
Skills that call the API read two environment variables:
export MOUNTAYA_PUBLISHABLE_KEY="pk_..."
export MOUNTAYA_SECRET_KEY="sk_..."
Create both in the Mountaya app, under your
organization's API keys tab. The secret key stays on a server: it does one thing, which is
mint short-lived session tokens. mountaya-auth explains the rest.
MCP server
https://mcp.mountaya.com/ exposes the Data API as read-only tools. mcp/servers.json is the
one place its configuration is written; every per-agent file in this repository, and the snippets
inside the mountaya-mcp skill, are rendered from it.
Engineering plugins
For people working on a Mountaya repository. Each is a Claude Code plugin; its skills are
plain SKILL.md files any agent can install with npx skills add <ai-repo> --skill <name>.
| Plugin | Ships | Enable for |
|---|---|---|
mountaya-core | graph-first (Entire Graph before searching by hand) and retrieve-via-ctx skills, a session banner that reports Entire's state, a guard that keeps git and Entire's repository, trail and setup commands the person's | every repository |
mountaya-typescript | typescript-conventions, google-typescript-best-practices, helix-ts-discipline | repositories with TypeScript |
mountaya-dart | dart-conventions, a guard against dart compile artifacts | repositories with Dart |
mountaya-flutter | flutter-conventions | repositories with Flutter |
mountaya-kotlin | kotlin-conventions | repositories with Kotlin |
mountaya-swift | swift-conventions | repositories with Swift |
A guard lives in the narrowest plugin where its rule always holds. A guard that fires where its rule does not hold teaches the reader to ignore guards.
Third-party skills are not redistributed here. Each repository vendors the ones it needs with npx skills, which records them in skills-lock.json.
One setup for every repository
A Mountaya repository does not hand-write its agent configuration. It keeps one file,
.agents/manifest.json, naming the plugins and MCP servers it needs and its own permissions:
{
"plugins": ["mountaya-typescript"],
"mcp": ["playwright"],
"permissions": { "deny": ["Bash(npm publish:*)"], "allow": ["Bash(npm run lint)"] },
"siblings": ["schemas"]
}
Its gate lives beside its toolchain, in mise.toml: every repository has a ci task (the gate),
a ci:quick task (formatting and linting) and the ones that ship a deploy task, so
mise run ci is the gate in every repository whatever it is written in.
scripts/apply.mjs combines it with workspace/baseline.json (model, effort, where repositories
live, the git and Entire deny lists, tooling) and mcp/servers.json, then renders:
| File | What is managed |
|---|---|
.claude/settings.json | Model, effort, marketplaces, plugins, enabled MCP servers, permissions. Hooks and any other key are left as found. |
.mcp.json, .cursor/mcp.json, .codex/config.toml | The whole file, removed (with a folder it leaves empty) when it would declare no server |
.claude/rules, .claude/skills/* | Symlinks into .agents/rules and .agents/skills |
AGENTS.md | The block between the two mountaya-ai:tooling markers. The file itself is required: it is the entry point for every agent. The agent guide entire brain setup and entire graph setup write is taken out again: the tooling block says the same once |
CLAUDE.md | Created as @AGENTS.md when missing; a check fails when it does not start with that import |
CONTRIBUTING.md | The "Working with an AI agent" section between the two mountaya-ai:contributing markers, created with the file when missing |
.gitignore | The block every repository ignores: per-machine agent state, .DS_Store, .env files and stray .claude/ folders below the root |
.editorconfig, .gitattributes | The shared head of each: editor defaults, and LF line endings. A repository's own sections and lines follow it |
.entire/settings.json | Session push (always, but never in a standalone repository), commit linking, telemetry and redaction |
.agents/setup | One command that sets a clone up, from Entire to the toolchain: sh .agents/setup (--check to report only). It runs scripts/setup.mjs from the ai checkout beside the repository, installs mise where mise.toml pins a toolchain, and runs the manifest's setup on it |
.githooks/ | From mise.toml's tasks: pre-commit (mise run ci:quick, after sh .agents/siblings sync pins and stages each sibling whose HEAD moved forward), pre-push (which on a push to main, from any local branch, warns about each of the manifest's pushWarnings, and stops a push only where sh .agents/siblings verify finds a pin CI could never fetch), and install, which wires them beside Entire's own git hooks, removes the hooks of that chain nothing runs any more, and which rendering runs when they are missing |
.depot/workflows/ci.yml | The gate on Depot CI, mise run ci, for every push to Entire: one job, or the parallel jobs the manifest's ciJobs splits it into. A repository that ships has its own ship.yml, which calls it first |
.agents/siblings | Pins the sibling commits CI builds against in siblings.lock (pin, and sync before every commit), stops a push carrying a pin CI could never fetch (verify), shows where each pin stands (status) and fetches them in CI; in a repository another one reads, publishes each pushed commit, in CI, as the git bundle those fetch (baseline siblings) |
node ../ai/scripts/apply.mjs # from a repository: render it
node ../ai/scripts/apply.mjs --check # exit 1 on drift
make apply # from here: every sibling repository
The rendered files are committed, so a contributor who never checks out this repository still
gets a working setup. Every Mountaya repository, public or internal, has the same shape: an internal
contributor and an outside one open the same AGENTS.md, get the same settings and read the
same onboarding section. To change something everywhere, edit the baseline and run make apply.
The full list of what every repository follows, and which of it is rendered or checked, is workspace/STANDARD.md.
Requirements
| Tool | How it is installed | What needs it |
|---|---|---|
| Node, Python, jq | pinned in mise.toml | The generator, the helpers and their fixture tests |
| npm | comes with Node | The hook fixture tests |
| make, curl | ship with the system | make check, and the helpers that fetch over HTTP |
Setup
sh .agents/setup # Entire, mise and the pinned tools, the git hooks, the dependencies
sh .agents/setup --check # what is missing, changing nothing
Commands
| Command | What it does |
|---|---|
mise run lint | The skills, plugins and generated files, validated |
mise run test | The hook, setup and helper fixture tests |
mise run ci:quick | What pre-commit runs: drift and validation |
mise run ci | The gate: all of the above |
Pre-commit runs mise run ci:quick. Every push to Entire runs mise run ci on Depot CI
(.depot/workflows/ci.yml), and its result shows as checks on the commit.
Development
make sync # rebuild providers/, the marketplaces and the shared blocks
mise run ci # the gate (make check): drift + validation + hook, setup and helper tests
skills/, plugins/, mcp/, workspace/ and VERSION are sources. providers/, the three
marketplace.json files, gemini-extension.json and every _mountaya_http.py are outputs:
make check fails if one is edited by hand. See CONTRIBUTING.md.
License
MIT. See LICENSE.md. The google-typescript-best-practices skill is derived from
the Google TypeScript Style Guide and stays under Apache-2.0, as its frontmatter declares.