Contributing to UDIOT

The framework and website are separate repositories. Framework implementation, tests and machine-readable release contracts live in the framework checkout; all maintained documentation is authored in the website's content/docs/ and published at udiot.in.

Work on the framework

Use Node >=22.17.0 and npm >=9. From a framework checkout:

git submodule update --init apps/udiot.in
npm ci
npm run build
npm run api:check
npm run test:docs

The website repository is private. Contributors need repository access to initialize its submodule; public npm consumers do not need that access. Documentation checks fail with an initialization instruction if it is missing. Do not create a replacement guide set in the framework repository.

Framework CI checks out the exact website commit recorded in its submodule pointer. For the private website repository, configure the framework repository secret UDIOT_WEBSITE_TOKEN with read-only access to tagnatech/udiot.in. The default GitHub token can only read its own repository. Website CI builds its own local content and needs no cross-repository token.

Run applicable framework tests for the changed behavior. Use npm run test:release for release tooling, and the packed consumer, browser and service checks described in publishing when relevant.

Change an API or guide

1. Change implementation and meaningful tests in the framework.
2. Build and inspect npm run api:check. For intentional API changes, regenerate npm run api:snapshot and review its diff.
3. Edit the affected page under apps/udiot.in/content/docs/.
4. Regenerate the public inventory with npm run docs:api when declarations change. That command writes directly into the website source.
5. Run npm run test:docs, then build and test the website.
6. Review and commit website changes in its own repository; record the reviewed website commit in the framework submodule pointer with the related change.

For a framework release, update website content/framework.json, app.mjs, the pinned dependency and lockfile, versioned copy and examples together. The framework checker rejects a documentation/package version mismatch.

Complete examples marked typescript check compile strictly and run offline. They must be bounded and self-contained. Other snippets may require application fixtures, credentials, services or a browser; label their assumptions.

Documentation ownership

Use project coverage to find the guide for a subsystem. The support policy owns compatibility classifications and the security policy owns reporting guidance. The API review guide describes how contributors preserve contracts.

Framework root README/install/quick-start/publishing/support/security files are short entry points to this site. Keep them as navigation, except the minimal private reporting contact needed by package and repository consumers. CHANGELOG.md is an automation-generated release artifact; API snapshots, readiness JSON, governance metadata and observability templates remain beside the tooling that consumes them. They are inputs and evidence, not parallel prose.

Old plans, issue specifications, audits and completion reports are preserved in the website repository's archives/, excluded from public output and search. Their dates, claims and code samples are historical; do not use them to infer current behavior. .planning/, bundled skills, tool instructions, third-party license notices and independent application repositories retain their own roles.

See framework validation, CI runners and website development and deployment for verification and operations.