PRD from an end-user perspective

[stephenfuqua]

This PR reverse-engineers a PRD from the application, primarily from the end-user perspective. Does not attempt to describe the DSL in detail or how to "transpile" the DSL into other formats.'

Additionally, the PR reverse-engineers a README for each package in the repository.

[github-actions]

Test Results

    1 files    457 suites   11m 21s ⏱️
5 534 tests 5 531 ✅ 3 💤 0 ❌
6 340 runs  6 337 ✅ 3 💤 0 ❌

Results for commit e28b7f3.

♻️ This comment has been updated with latest results.

[Copilot]

Pull request overview

This documentation-only PR adds an end-user-oriented MetaEd 4.x PRD and package-level README coverage across the monorepo, describing package roles, inputs, outputs, and business logic.

Changes:

• Adds docs/PRD-4.x.md with product scope, requirements, architecture, limitations, and glossary.
• Adds README files for packages that previously lacked package-level documentation.
• Updates existing package READMEs to use the new Input Configuration / Output / Business Logic structure.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/PRD-4.x.md	Adds the MetaEd 4.x product requirements document.
packages/metaed-core/README.md	Documents core pipeline configuration, outputs, and orchestration role.
packages/metaed-console/README.md	Updates CLI build documentation.
packages/metaed-default-plugins/README.md	Documents default plugin stack assembly.
packages/metaed-odsapi-deploy/README.md	Documents deployment library inputs, outputs, and task flow.
packages/metaed-odsapi-deploy-console/README.md	Documents deployment CLI options and workflow.
packages/metaed-plugin-edfi-api-catalog/README.md	Updates API catalog output and processing documentation.
packages/metaed-plugin-edfi-api-schema/README.md	Documents API schema configuration and generated JSON outputs.
packages/metaed-plugin-edfi-data-catalog/README.md	Adds documentation for a data catalog plugin.
packages/metaed-plugin-edfi-handbook/README.md	Documents handbook HTML and Excel outputs.
packages/metaed-plugin-edfi-ods-changequery/README.md	Documents shared change-query artifacts.
packages/metaed-plugin-edfi-ods-changequery-postgresql/README.md	Documents PostgreSQL change-query generation.
packages/metaed-plugin-edfi-ods-changequery-sqlserver/README.md	Documents SQL Server change-query generation.
packages/metaed-plugin-edfi-ods-postgresql/README.md	Documents PostgreSQL ODS SQL generation.
packages/metaed-plugin-edfi-ods-recordownership/README.md	Documents shared record-ownership metadata enrichment.
packages/metaed-plugin-edfi-ods-recordownership-postgresql/README.md	Documents PostgreSQL record-ownership DDL output.
packages/metaed-plugin-edfi-ods-recordownership-sqlserver/README.md	Documents SQL Server record-ownership DDL output.
packages/metaed-plugin-edfi-ods-relational/README.md	Documents relational ODS model enrichment.
packages/metaed-plugin-edfi-ods-sqlserver/README.md	Documents SQL Server ODS SQL generation.
packages/metaed-plugin-edfi-odsapi/README.md	Documents ODS/API metadata JSON generation.
packages/metaed-plugin-edfi-sql-dictionary/README.md	Documents SQL data dictionary output.
packages/metaed-plugin-edfi-unified/README.md	Documents shared unified model transformations.
packages/metaed-plugin-edfi-unified-advanced/README.md	Documents advanced unified validation rules.
packages/metaed-plugin-edfi-xml-dictionary/README.md	Documents XML data dictionary output.
packages/metaed-plugin-edfi-xsd/README.md	Documents XSD schema generation.

[bradbanister]

I found a large number of issues and decided to stop after several iterations, so there may well be more. These were found with the help of gpt-5.5 xhigh, though of course I reviewed them all.

• Findings

• High: The PRD has detailed VS Code extension requirements, but that implementation lives in the separate vscode-metaed-ide repo. The MetaEd-js repo has no relationship to VS Code Extensions.

• High: docs/PRD-4.x.md:226 names @edfi/metaed-odsapi-deploy as the CI deploy package, but that package is only the deploy task library and exports runDeployTasks; the CLI wrapper is @edfi/metaed-
  odsapi-deploy-console. See packages/metaed-odsapi-deploy/src/index.ts:6 and packages/metaed-odsapi-deploy-console/package.json:2.

• High packages/metaed-odsapi-deploy-console/README.md:23 says deploy-console always runs the MetaEd build pipeline before deploying. In --config mode it does not; it uses the configured
  artifactDirectory and only runs deploy tasks. Only the --source/--target/--projectNames path builds first. This will mislead CI/deploy users.

• High: Deploy deletion semantics are overstated in docs/PRD-4.x.md:146 and packages/metaed-odsapi-deploy/README.md:36. Deployment writes current extension artifacts under the versioned path in
  packages/metaed-odsapi-deploy/src/task/DeployExtension.ts:49, but deletion only removes the legacy top-level EdFi.Ods.Extensions.{projectName}/Artifacts path in packages/metaed-odsapi-deploy/src/
  task/RemoveExtensionArtifacts.ts:20. The docs currently imply a clean deploy of existing extension artifact directories, which is not what happens for the versioned target.

• High: packages/metaed-odsapi-deploy-console/README.md:12 says --projectNames are “Project names to deploy.” They are actually positional project-name overrides passed to scanForProjects, not a
  deploy filter. See packages/metaed-odsapi-deploy-console/src/metaed-odsapi-deploy-console.ts:129 and packages/metaed-core/src/project/ProjectLoader.ts:52.

• Medium: Change-query docs conflate the common package with the database-specific companion plugins. packages/metaed-plugin-edfi-ods-changequery/README.md:3 says the common package generates SQL,
  but its initializer registers only a validator in packages/metaed-plugin-edfi-ods-changequery/src/index.ts:63; the SQL generators are registered by the PostgreSQL and SQL Server packages. The PRD’s
  file list at docs/PRD-4.x.md:169 should also avoid hardcoded or wrong names: tracked-delete and trigger filenames vary by target style/version.

• Medium: packages/metaed-plugin-edfi-unified/README.md:8 incorrectly calls the unified plugin a pure enhancer that only enriches the model. The package registers both validatorList() and
  enhancerList() in packages/metaed-plugin-edfi-unified/src/index.ts:405, the plugin has the largest set of validators, and the README should describe both validation and enhancement responsibilities.

• Medium: docs/PRD-4.x.md:175 hardcodes extension SQL/XSD artifacts as EXTENSION-prefixed. The implementation uses each namespace’s projectExtension or namespace name, for example in SQL packages/
  metaed-plugin-edfi-ods-sqlserver/src/generator/OdsGeneratorBase.ts:16 and XSD packages/metaed-plugin-edfi-xsd/src/generator/XsdGenerator.ts:34.

• Medium: Documentation artifact paths are inconsistent from the artifact root. WriteOutput prepends the generated output namespace, so namespace: 'Documentation' plus folder names produces paths
  like Documentation/Ed-Fi-Handbook/... and Documentation/DataDictionary/...; several docs omit that prefix, including docs/PRD-4.x.md:212, packages/metaed-plugin-edfi-handbook/README.md:13,
  packages/metaed-plugin-edfi-sql-dictionary/README.md:14, and packages/metaed-plugin-edfi-xml-dictionary/README.md:14.

• Medium: Extension project validation is documented as enforced requirements in docs/PRD-4.x.md:216, including project name and SemVer rules. Locally, scanForProjects just reads metaEdProject and
  derives namespaceName; it does not validate those constraints, and SemVer is only a string alias. See packages/metaed-core/src/project/ProjectLoader.ts:37 and packages/metaed-core/src/
  MetaEdEnvironment.ts:14.

• Medium: packages/metaed-odsapi-deploy-console/README.md:11 says --target is the ODS/API repository path. The implementation resolves paths like Ed-Fi-ODS/... and Ed-Fi-ODS-Implementation/... under
  deployDirectory, so this must be the parent directory containing those repos. See packages/metaed-odsapi-deploy/src/task/ExtensionProjectsExists.ts:13.

• Medium: docs/PRD-4.x.md:144 and packages/metaed-odsapi-deploy/README.md:36 imply extension artifacts deploy generally, while only core is version-qualified. DeployExtension also no-ops when
  defaultPluginTechVersion < 7.0.0. See packages/metaed-odsapi-deploy/src/task/DeployExtension.ts:118.

• Medium: docs/PRD-4.x.md:155 says pluginConfigDirectories contains paths to configuration files. The loader treats them as directories and searches each one for {pluginShortName}.config.jsonnet
  or .json. See packages/metaed-core/src/plugin/LoadPluginConfiguration.ts:111.

• Medium: docs/PRD-4.x.md:162 says namespace, core, and extensions are mutually exclusive. Joi only rejects namespace with core/extensions; it does not reject core plus extensions, and matching
  checks core first. See packages/metaed-core/src/plugin/ConfigurationSchema.ts:66 and packages/metaed-core/src/plugin/AnnotateModelWithConfiguration.ts:41.

• Medium: packages/metaed-core/README.md:12 describes pluginTechVersion as controlling plugin selection. It is currently unused; plugin setup assigns every plugin defaultPluginTechVersion. See
  packages/metaed-core/src/plugin/PluginSetup.ts:13.

• Medium: packages/metaed-plugin-edfi-xsd/README.md:12 says interchange schemas are generated under XSD/. They are generated under Interchange/. See packages/metaed-plugin-edfi-xsd/src/generator/
  InterchangeGenerator.ts:39.

• Medium: packages/metaed-plugin-edfi-sql-dictionary/README.md:7 says it depends on relational ODS model data, but the generator reads SQL Server-specific table/column metadata from
  data.edfiOdsSqlServer. See packages/metaed-plugin-edfi-sql-dictionary/src/generator/SqlDataDictionaryGenerator.ts:38.

• Medium: packages/metaed-plugin-edfi-ods-sqlserver/README.md:21 and packages/metaed-plugin-edfi-ods-postgresql/README.md:21 say the ODS plugins generate “authorization views.” The implementation
  registers education organization authorization index generators, not view generators. See packages/metaed-plugin-edfi-ods-sqlserver/src/index.ts:9.

• Medium: The pipeline order is documented as global validate -> enhance -> generate -> write in docs/PRD-4.x.md:309 and packages/metaed-core/README.md:29, but execution is per plugin: validators,
  then enhancers, then generators for each plugin before moving to the next plugin. See packages/metaed-core/src/pipeline/Pipeline.ts:76.

• Medium: docs/PRD-4.x.md:219 presents a required extension directory structure, but the loader recursively reads any .metaed files under each configured project path and does not enforce those
  directory names. See packages/metaed-core/src/file/FileSystemFilenameLoader.ts:52.

• Low packages/metaed-console/README.md:9 says --config is relative to the working directory. The console code resolves the config path relative to __dirname, so relative paths are not cwd-relative
  in the implementation.

• Low: docs/PRD-4.x.md:288 says the common record-ownership plugin generates database artifacts. It has enhancers only and no generators; artifacts come from the PostgreSQL/SQL Server companion
  packages. See packages/metaed-plugin-edfi-ods-recordownership/src/index.ts:13.

• Low: docs/PRD-4.x.md:296 describes metaed-plugin-edfi-unified-advanced as an advanced model layer for generation. It is validators-only. See packages/metaed-plugin-edfi-unified-advanced/src/
  index.ts:22.

• Low: packages/metaed-console/README.md:31 says to build from the parent directory and then run node ./dist/index.js; from the repo root the actual path is packages/metaed-console/dist/index.js, as
  reflected by the root metaed:build script in package.json:38.