Install AletheIA

Add the AletheIA operating overlay to a project, configure its boundaries, and verify the installation.

AletheIA is installed as a project operating overlay, not as an autonomous runtime. The overlay gives human and AI collaborators shared instructions, project boundaries, and places for decisions, evidence, handoffs, and learnings.

15–30 minutes Existing or new project No runtime replacement

Before you begin

You need:

Node.js 18 or newer;
Microsoft Agentic Package Manager (APM) available as apm;
a Git repository or project directory;
permission to add project-level guidance files;
a clean commit before adopting the overlay in an existing project.

node --version
apm --version
git status --short

Choose an adoption path

Install with APM

Recommended for a reproducible package download and lockfile, followed by explicit overlay materialization.

Adopt manually

Use the canonical pack instructions when APM is unavailable or your environment requires manual review before copying files.

Install with APM

Download and lock the package

From the project root, install the currently published APM package:

apm install nevitonsantana/AletheIA#v1.0.2-apm --target claude,codex,copilot

This creates apm_modules/AletheIA/ and apm.lock.yaml. Commit the lockfile so collaborators and continuous integration resolve the same package content.

Materialize the operating overlay

Still in the consumer project root, run:

apm run scaffold-overlay

The scaffold refuses to overwrite existing AGENTS.md, CLAUDE.md, .claude/, or ops/ai/ paths. Review conflicts rather than forcing an overwrite by default.

Replace project variables

Find the placeholders in the generated guidance:

grep -r '{{' AGENTS.md CLAUDE.md .claude/settings.json

Replace them with the project name, purpose, stack, and real install, test, lint, build, and development commands. Repeat the check until no placeholder remains.

Write the minimum constitution

Replace the placeholder in ops/ai/constitution/ with four short, source-backed files:

File	Minimum answer
`mission.md`	What does this project do, and for whom?
`scope.md`	What is in scope, out of scope, or explicitly undecided?
`stack.md`	Which technologies are used, and which commands validate them?
`principles.md`	Which rules must humans and AI collaborators preserve?

Verify before real work

Confirm the expected surfaces exist and the generated files contain no placeholders:

test -f AGENTS.md
test -d ops/ai/constitution
! grep -r '{{' AGENTS.md CLAUDE.md .claude/settings.json
git diff --check

Then open a fresh runtime session from the project root and ask it to summarize the mission, scope, validation commands, and stop conditions without changing files.

What the overlay adds

project/
├── AGENTS.md
├── CLAUDE.md
├── .claude/
│   ├── settings.json
│   └── rules/
└── ops/ai/
    ├── constitution/
    ├── handoffs/
    ├── reports/
    ├── policies/
    ├── schemas/
    ├── skills/
    └── learnings/

These paths establish shared operating context. They do not grant permissions, install a security sandbox, select a model, or authorize autonomous action.

the overlay paths exist;
no template variable remains;
mission, scope, stack, and principles describe the real project;
the selected runtime can summarize those boundaries;
no write, permission, or security capability is being inferred from installation alone.

Install AletheIA

Before you begin

Choose an adoption path

Install with APM

What the overlay adds

Runtime-specific setup

Troubleshooting

APM installs the package, but the overlay is missing

The scaffold reports existing files

The runtime ignores the project boundaries

A command in the generated guidance is wrong

Installation acceptance check

Next steps