Onboard a repository

Goal: give Kiyo durable, evidence-backed context about your repository, with nothing written that you did not approve. Skill: Init · Walkthroughs: WT-01 (empty repository), WT-02 (existing .NET and Angular monorepo)

1. Preview first

Select Init and send:

Preview onboarding for this repository; report evidence, unknowns and proposed Memory/config/bootstrap changes without writing files.

For a monorepo, name the component. Init scopes discovery and any later state to it:

Onboard this repository using its existing Memory location. Inspect representative backend/frontend files; preserve application files and human instruction sections.

Verify: git status shows no changes. The report lists sampled paths, unknowns, proposed profiles, and the exact proposed file delta.

2. Review the proposal

Look for these in the report:

Item	What good looks like
Inspected scope	Specific files and sections, within the 16-file / 1,200-line budget, or an explained expansion
Unknowns	Named gaps (versions, deployment, business rules) rather than guesses
Profiles	Chosen from actual config and source, e.g. `global.json` and `.csproj` for .NET, `angular.json` for Angular
Paths	Existing Memory or config paths reused; new defaults only for an unconfigured project
Managed block	Proposed only if persistent guidance is needed and your host’s instruction file is known

If a profile is suggested because of a folder name alone, that is weak evidence. Ask for the source.

3. Initialize what you approve

Create only the proposed project-local Memory/config with unknowns retained.

For a new project this typically creates .kiyo/policy.md, .kiyo/memory/index.md, and only the topic files that have real entries. Init never:

scaffolds application code or initializes Git;
installs dependencies or changes global settings;
runs your build, tests, or migrations.

Verify:

git status --short
git diff --stat

Only .kiyo/ files, plus the managed block if you asked for one, should appear.

4. Optional: persistent project guidance

If you want every session to be pointed at Kiyo state, ask Init to add the managed block. Init inserts one marked block into your existing host instruction file and preserves every other line. It never replaces the whole file, touches AGENTS.override.md, or changes global configuration. The block must stay within 250 words.

Whether your host then loads that block automatically in new sessions is NOT_TESTED. Keep selecting Skills explicitly.

Common pitfalls

Pitfall	Why it matters	Fix
Asking Init to “also fix the lint errors it found”	Init never repairs application defects	Start a separate Implement task
Two Memory stores after a manual copy	Kiyo keeps one canonical store; two locations block writes	Decide which store is canonical; Kiyo will not merge by timestamp
Expecting Init on every feature	Init runs only when requested	Use daily Skills; rerun Init only for onboarding changes
Empty repository	Stack stays Unknown by design	Initialize minimal state with unknowns retained