docs: add DeepWiki entry point and Pages-ready product guide

README.md

@@ -1,23 +1,21 @@
 # aFIPC
 
-Automated Fixed Item Parameter Calibration (FIPC) for IRT test linking.
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ContextualWisdomLab/aFIPC)
 
-This package contains the original graduate-school implementation used to
-produce accurate fixed-item linking results. The current maintenance goal is to
-preserve numerical behavior while modernizing repository operations
-(documentation, CI, and dependency hygiene).
+Automated Fixed Item Parameter Calibration (FIPC) for IRT test linking and equating. aFIPC helps psychometric teams preserve score-scale continuity across test forms by fixing anchor-item parameters while estimating parameters for newly administered items.
 
 ## What this repository contains
 
 - `R/aFIPC.R`: core `autoFIPC()` implementation
 - `DESCRIPTION`, `NAMESPACE`, `man/`: package metadata and generated docs
 - `packrat/`: historical dependency lock/vendor directory
 - `.github/workflows/`: CI/security automation
+- `docs/index.md`: product, architecture, onboarding, and release-facing documentation
 
 ## Development status
 
-- Algorithmic core is legacy but trusted for historical outputs.
-- Operational guardrails are now maintained via GitHub Actions and Dependabot.
+- Algorithmic behavior is preserved for compatibility with established linking outputs.
+- Operational guardrails are maintained via GitHub Actions and Dependabot.
 - Legacy `packrat` bootstrap is opt-in via `AFIPC_ENABLE_PACKRAT=true`.
 - Broken host-specific `packrat/lib-R` symlinks were removed for portable builds.
 - Architectural and agent operation docs are available in:
@@ -50,6 +48,5 @@ R_PROFILE_USER=/dev/null Rscript -e \
 ## Maintenance policy
 
 - Prefer preserving equation/calibration behavior over refactoring.
-- Avoid silent behavioral changes in `autoFIPC()` without explicit regression
-  evidence.
+- Avoid silent behavioral changes in `autoFIPC()` without explicit regression evidence.
 - Keep CI green on supported runners and keep Actions pinned/updated.

docs/index.md

@@ -0,0 +1,50 @@
+# aFIPC
+
+Automated Fixed Item Parameter Calibration for item-response-theory linking and equating.
+
+## Product responsibility
+
+aFIPC preserves a common measurement scale across test forms by combining anchor-item parameters from a reference form with calibration of newly administered items. It is intended for psychometric workflows where score comparability across administrations matters and fixed-item linking is the chosen design.
+
+## Core workflow
+
+1. Prepare reference-form and new-form response data with a stable set of common items.
+2. Fit or supply the reference-form item parameters used as linking anchors.
+3. Run `autoFIPC()` to construct the fixed-item calibration workflow for the new form.
+4. Review model diagnostics and linking outputs before downstream score reporting or operational use.
+
+## Architecture
+
+The repository is an R package with a focused calibration core:
+
+- `R/aFIPC.R` contains the main fixed-item linking workflow.
+- `R/surveyFA.R` contains supporting analytical routines used by the package.
+- `DESCRIPTION`, `NAMESPACE`, and `man/` define package metadata and generated reference documentation.
+- `ARCHITECTURE.md` documents structural boundaries and maintenance constraints.
+- `.github/workflows/` provides continuous-integration and security checks.
+
+The package keeps established numerical behavior as a compatibility constraint; behavioral changes should be supported by regression evidence rather than incidental refactoring.
+
+## Onboarding
+
+Clone the repository, use a current R toolchain, and run the package checks before changing calibration behavior:
+
+```bash
+R_PROFILE_USER=/dev/null Rscript -e \
+'install.packages(c("rcmdcheck"), repos="https://cloud.r-project.org")'
+R_PROFILE_USER=/dev/null Rscript -e \
+'rcmdcheck::rcmdcheck(args = c("--no-manual", "--as-cran"), error_on = "warning")'
+```
+
+For contributor expectations and architectural context, read `CONTRIBUTING.md` and `ARCHITECTURE.md` before modifying estimation or linking logic.
+
+## Releases and change control
+
+The repository currently does not publish GitHub Releases. Until a tagged release is available, consumers should pin an explicitly tested commit or package build and review the repository history for behavioral changes. Calibration changes should preserve reproducibility and be accompanied by test evidence.
+
+## Documentation and support
+
+- Repository README: concise product and contributor entry point.
+- `ARCHITECTURE.md`: package boundaries and design context.
+- `man/`: generated R reference documentation.
+- [Ask DeepWiki](https://deepwiki.com/ContextualWisdomLab/aFIPC): repository-aware documentation and code navigation.