# Repository guide for coding agents
This repository owns the `docxcraft` Rust library. Read [README.md](README.md)
for setup and [docs/agent-guide.md](docs/agent-guide.md) for API signatures,
ownership, units, chart input and troubleshooting.
## Layout and boundaries
- `src/lib.rs` is the public API entry point; read the target module before using
or changing a method. Sibling Office crates have different constructors.
- `examples/basic.rs` and `examples/chart.rs` are runnable consumer programs.
- `tests/export.rs` checks actual Office ZIP contents and chart data.
- Bundled XML templates are required at compile time; keep them in the package include list.
- This crate has its own manifest and Git history. It does not inherit metadata
or a workspace from Reporsa.
- `xlsxcraft` is a registry dependency; use the documented local Cargo override
before its first publication or during cross-repository changes.
## Work and verification
Preserve existing Rust style and keep changes focused. For behavior changes,
add a deterministic regression test and update relevant examples and docs.
Use temporary output paths in tests and `target/` for manual generated files.
Keep tests independent of Office installations, external services and credentials.
```bash
cargo fmt --all -- --check
cargo test
cargo check --examples
cargo run --example basic
cargo run --example chart
```
Run these commands from the repository root; use `--offline` for Cargo
build/test commands only when dependencies are cached.
The README is included as crate-level documentation, so its Rust examples must
compile as doctests. `cargo doc --no-deps` generates local API documentation.
Keep source and assets in `Cargo.toml`'s package include list when adding files.
Check `cargo package --list` for packaging changes. Build success and XML
assertions do not establish visual fidelity in every Office viewer; state what
was actually verified.
## Repository conventions
`Cargo.lock`, `target/` and `.cargo/config.toml` are ignored local artifacts.
Do not commit credentials or generated Office files. Use concise, imperative
English commit subjects and describe validation in pull requests.
Sources use `AGPL-3.0-only`. Preserve license/SPDX and provenance notices.
[LICENSING.md](LICENSING.md) records the possibility of separate commercial
terms; it does not grant a commercial exception. Maintainer publication steps
are in [RELEASING.md](RELEASING.md).
## Licensing maintenance
The copyright holder is ALGFORCE INC.; the public licensing contact is
founders@exceldashboard.ai. External code PRs are not currently accepted while contribution
terms are being established; issues remain welcome. This policy does not limit
AGPL rights and does not introduce a CLA or commercial exception.
`THIRD_PARTY.md` records reference dependencies. After dependency or packaging
changes, run `cargo run --example license_inventory -- --check-package` and
review the fresh inventory, copied notices and any missing notice files.
The tool lives in `tools/license_inventory.rs` and writes under ignored
`target/license-inventory/`. Retain the AGPL license unchanged and preserve the
separate MPL text in `licenses/`.