Complete the repository-specific operating guide

stages: [verify]

verify-docs:

handbook-links:

  stage: verify

  script: test -s README.md

  script:

    - python3 tools/check_links.py

# Engineering handbook

# Fieldwork engineering handbook

Fieldwork teams build and operate client request, document and delivery services.

Operating notes for the client, integration and records services.

- [Fieldwork Connect](https://api.fieldharbor.xyz/): Integration requests, partner onboarding and delivery coordination.

- [Fieldwork Studio](https://studio.fieldharbor.xyz/): Project delivery, working documents and progress reviews for client teams.

- [Fieldwork Gateway](https://gateway.fieldharbor.xyz/): Partner services, request routing and status information.

- [Fieldwork Service Desk](https://desk.meadowgrid.xyz/): Team requests, delivery commitments and review records.

- [Fieldwork Records](https://records.meadowgrid.xyz/): Project records, approval notes and document review.

- [Fieldwork Intake](https://forms.meadowgrid.xyz/): A shared intake desk for project briefs and supporting files.

- [Fieldwork Code](https://code.fieldharbor.xyz/): Source repositories, issues and engineering documentation.

- [Service responsibilities](docs/services.md)

- [Access and ownership](docs/access.md)

- [Review workflow](docs/review.md)

- [Deployment and recovery](docs/operations.md)

Requests belong in the service that owns the decision; engineering issues belong in its source repository.

# Access and ownership

Sarah Kwan owns engineering access. Marco Delgado maintains integrations and the service registry. Ana Alvarez coordinates delivery reviews. Evan Osberg handles the operations queue, and Leah Lewis reviews records and supplier documentation.

Use your assigned account to review records. Include the service name, record reference and requested role in an access request to the service desk. Owners confirm the request before changing an assignment.

# Review workflow

# Deployment and recovery

Changes need an owner, a recovery plan and a validation result. Keep credentials outside repositories. Record client-visible changes in the monthly delivery note.

Before changing a service, capture its application revision and back up its state database. Apply its migration before restarting the web process. Validate login, a record update and a document download.

If a migration fails, keep the service unavailable until the database and application revision agree. Restore the database snapshot with the matching application revision, then repeat the same validation journey. Record the outcome in the repository issue.

# Record review

1. Open the service workspace and select the record.

2. Read its owner, status and supporting document.

3. Add a note explaining the decision.

4. Set the appropriate review state.

5. Save and verify the note is visible after reloading.

Document states are Pending review, Approved and Needs changes. Request states are Received, In review, Waiting for information and Completed. Support tickets use Open, In progress, In review and Resolved.