docs: improve documentation and clean up project configuration (#2)

* reorient make tasks and clean up gen-project config

* updates to config

* move docs related javascript files

* update readme, add other excel templates

Author: clevinson

CONTRIBUTING.md

@@ -3,7 +3,8 @@
 :+1: First of all: Thank you for taking the time to contribute!
 
 The following is a set of guidelines for contributing to
-oae-data-protocol. These guidelines are not strict rules.
+oae-data-protocol. The bulk of this document is provided as default
+contributing guidelines for LinkML projects. These guidelines are not strict rules.
 Use your best judgment, and feel free to propose changes to this document
 in a pull request.
 

Makefile

@@ -195,18 +195,6 @@ examples/output: src/$(SCHEMA_NAME)/schema/$(SCHEMA_NAME).yaml
 serve: mkd-serve
 
 
-# Generate dyanmic enums
-
-ontologies/sea_names.ttl:
-	rm -rf ontologies/sea_names.ttl
-	curl 'https://vocab.nerc.ac.uk/collection/C16/current/' -H "Accept: text/turtle" > ontologies/sea_names.ttl
-
-enums: ontologies/sea_names.ttl
-	vskit expand -s src/oae_data_protocol/schema/dynamic_enums.yaml -o src/oae_data_protocol/schema/dynamic_enums_expanded.yaml --config vskit-config.yaml
-
-json-schema:
-	gen-json-schema src/oae_data_protocol/schema/oae_data_protocol.yaml -t OAEProject --title-from title > $(JSON_SCHEMA_OUT)
-
 
 # Python datamodel
 $(PYMODEL):

README.md

@@ -1,34 +1,104 @@
-# oae-data-protocol (⚠️ work in progress ⚠️)
+# OAE Data Protocol Schemas
 
-Base ontology and data schemas for ocean alkalinity enhancement projects, experiments, and field trails. This project aims to be a technical complement to Submarine Scientific's [OAE Data Protocol](https://www.carbontosea.org/oae-data-protocol/), developed in conjunction with Carbon To Sea and NOAA.
+> ⚠️ **Alpha Software**: These schemas are under active development and may change
+> without notice. We do not currently guarantee backwards compatibility between
+> versions. Once the schemas stabilize, we will establish a formal release process
+> with semantic versioning to support clients and integrators who need stability
+> guarantees.
 
-## Website
+The [OAE Data Management Protocol](http://carbontosea.org/oae-data-protocol/1-0-0/) outlines recommendations
+for producing consistent data and metadata for Ocean Alkalinity Enhancement (OAE) research projects.
 
-[https://clevinson.github.io/oae-data-protocol](https://clevinson.github.io/oae-data-protocol)
+This repository provides machine-readable schemas and data standards for the protocol. It focuses on formal specifications for metadata about OAE projects, experiments, and datasets—not the individual data variables within datasets themselves.
+
+**For Protocol Compliance**: As of the v1.0 protocol launch (August 25, 2025), projects seeking to comply with the protocol guidelines should use the Excel templates available on the [protocol website](http://carbontosea.org/oae-data-protocol/1-0-0/). These templates are also available in the [`templates/excel`](./templates/excel) directory of this repository.
+
+**Beta Testing**: Organizations and researchers interested in testing the software tooling under development in this repository should contact [jacki@submarine.earth](mailto:jacki@submarine.earth).
+
+## What's Inside
+
+This repository contains [LinkML](https://linkml.io) schema definitions that can generate:
+
+- **JSON Schema** for data validation and form generation
+- **Python dataclasses** for programmatic data handling
+- **Documentation** (what you're reading now!)
+- Support for multiple serialization formats (JSON, YAML, RDF, etc.)
+
+## Documentation
+
+📖 **[View the schema documentation](https://submarine-mrv.github.io/oae-data-protocol)**
+
+## Quick Start
+
+
+
+### Using the Schemas
+
+The generated schemas are available in the `project/` directory:
+
+- `project/jsonschema/` - JSON Schema definitions
+- `src/oae_data_protocol/datamodel/` - Python dataclasses
 
 ## Repository Structure
 
-- [examples/](examples/) - example data
-- [project/](project/) - project files (do not edit these)
-- [src/](src/) - source files (edit these)
-  - [oae_data_protocol](src/oae_data_protocol)
-    - [schema](src/oae_data_protocol/schema) -- LinkML schema
-      (edit this)
-    - [datamodel](src/oae_data_protocol/datamodel) -- generated
-      Python datamodel
-- [tests/](tests/) - Python tests
-
-## Developer Documentation
-
-<details>
-To run commands you may use good old make or the command runner [just](https://github.com/casey/just/) which is a better choice on Windows.
-Use the `make` command or `duty` commands to generate project artefacts:
-* `make help` or `just --list`: list all pre-defined tasks
-* `make all` or `just all`: make everything
-* `make deploy` or `just deploy`: deploys site
-</details>
-
-## Credits
-
-This project was made with
-[linkml-project-cookiecutter](https://github.com/linkml/linkml-project-cookiecutter).
+```
+├── src/
+│   └── oae_data_protocol/
+│       ├── schema/          # LinkML schema definitions (edit these!)
+│       └── datamodel/       # Generated Python dataclasses
+├── project/                 # Generated project files (don't edit)
+├── examples/                # Example data files
+├── tests/                   # Python tests
+└── docs/                    # Generated documentation
+```
+
+## Development
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/submarine-mrv/oae-data-protocol.git
+cd oae-data-protocol
+
+# Install dependencies
+make install
+
+# Generate schema artifacts
+make gen-project
+```
+
+### Common Commands
+
+```bash
+make help              # Show all available commands
+make gen-project       # Regenerate schemas and Python code
+make test             # Run tests
+make lint             # Lint LinkML schemas
+make serve            # Build and serve documentation locally
+```
+
+### Working with Schemas
+
+The schema files in `src/oae_data_protocol/schema/` are the source of truth. Edit these files and run `make gen-project` to regenerate all derived artifacts.
+
+## Project Status 
+
+**Current Status**: Alpha development
+
+We're actively developing and refining these schemas based on real-world usage and community feedback.
+Breaking changes may occur as we work toward a stable v1.0 release of these schemas which will have parity
+with v1.0.0 of the protocol.
+
+## Credits & Acknowledgments
+
+This project is built with:
+- [LinkML](https://linkml.io) for schema definitions
+- [linkml-project-cookiecutter](https://github.com/linkml/linkml-project-cookiecutter) for project structure
+
+Development of the OAE Data Protocol and its corresponding technical tooling has been made possible with 
+funding and steering support from [Carbon To Sea](https://carbontosea.org).
+
+## License
+
+See [LICENSE](./LICENSE) for details.

config.yaml

@@ -1,47 +1,19 @@
-# Configuration of generators (defaults illustrated)
+# Configuration of generators
+# See `make gen-project` task or https://linkml.io/linkml/generators/project-generator.html
 ---
 includes:
   - jsonschema
   - python
+
 generator_args:
-  excel:
-    mergeimports: true
-  owl:
-    mergeimports: true
-    metaclasses: true
-    type_objects: true
-    # throws 'Cannot handle metadata profile: rdfs'
-    # metadata_profile: rdfs
-  markdown:
-    mergeimports: true
-  graphql:
-    mergeimports: true
-  java:
-    mergeimports: true
-    metadata: true
-  jsonld:
-    mergeimports: true
   jsonschema:
     mergeimports: true
     include_null: false
     top_class: OAEProject
     title_from: title
-  jsonldcontext:
-    mergeimports: true
   python:
     mergeimports: true
-  prefixmap:
-    mergeimports: true
-  proto:
-    mergeimports: true
-  shacl:
-    mergeimports: true
-  shex:
-    mergeimports: true
-  sqlddl:
-    mergeimports: true
-  typescript:
-    mergeimports: true
-    metadata: true
 
-...
+# Unused generators (can be re-enabled as needed):
+# excel, owl, markdown, graphql, java, jsonld, jsonldcontext,
+# prefixmap, proto, shacl, shex, sqlddl, typescript