# FAQ — defapp

Last updated: 2026-07-22

## Getting started

**Q: How do I view defapp docs in a browser?**  
**A:** Place `defapp.docs.php` in the defapp app root next to the `docs/`
folder, then run `php -S localhost:8000` and visit `/defapp.docs.php`. The
index shows all docs listed in the manifest and their status.

**Q: How do I add a new doc to the viewer?**  
**A:** Create the Markdown file under `docs/` and add an entry to
`$docManifest` in `defapp.docs.php` with `file`, `title`, `purpose`,
and `useWhen`. Run `php -l defapp.docs.php` to verify syntax before
committing.

## Syntax errors and AI-generated code

**Q: Why does a PHP parse error keep “moving” when I fix it?**  
**A:** PHP often reports the point where it finally gets confused, not where the
problem started. Missing semicolons, unclosed arrays, or comments can cause
later lines to appear “unexpected”. Always check the lines just above the error
and run `php -l` after each change.

**Q: What is the standard way to test AI-generated PHP code?**  
**A:** Save the file, then run:
- `php -l file.php` for quick syntax validation.
- `php -d display_errors=stderr -f file.php` for full error output.

Never trust AI-generated code without local syntax tests.

**Q: How should I ask the AI for code to minimise syntax issues?**  
**A:** Prefer small, testable chunks when debugging and full-file output when
creating a new canonical file. Describe the outcome you want and provide the
current working version or context.

## Wizards and multi-step flows

**Q: What is a “wizard” in defapp?**  
**A:** A wizard is a guided multi-step flow that helps you complete a goal (such
as initialising defapp or adding a new doc) with clear steps and verification,
instead of a single complex one-shot command.

**Q: How do wizards help with AI collaboration?**  
**A:** Wizards make complex changes easier to reason about and test. Each step
can be described, implemented, and syntax-checked with AI assistance, reducing
the chance of hidden mistakes.

## Docs and standards

**Q: When should I update docs vs create a new version?**  
**A:** Update docs when you clarify behaviour, UX, or workflow. Create a new
version of standards or templates when you make breaking changes (e.g.,
changing manifest schema or required files).

**Q: Where do I record major changes?**  
**A:** In `docs/CHANGELOG.md`, with date, what changed, and why. For larger
changes, also update `docs/PROJECT_LOG.md` and relevant conceptual docs such
as `SPEC.md`, `ARCHITECTURE.md`, and `PROCESS.md`.