Imported from owncloud/notes (AGENTS.md). Install upstream with npx skills add owncloud/notes. Copyright stays with the author.

AGENTS.md -- Notes

Repository Overview

Distraction-free note-taking app for ownCloud Server with a RESTful API. Licensed under AGPL-3.0. PHP backend with JavaScript frontend.

Architecture & Key Paths

• controller/ -- HTTP controllers
• service/ -- Business logic services
• db/ -- Database mappers and entities
• js/ -- Frontend JavaScript
• css/ -- Stylesheets
• templates/ -- Server-side templates
• appinfo/ -- ownCloud app metadata
• l10n/ -- Translation files
• tests/ -- Unit and integration tests
• Makefile -- Build and test automation
• composer.json -- PHP dependencies

Development Conventions

• PHP code follows ownCloud coding standards (phpcs)
• Static analysis with PHPStan

Build & Test Commands

make build                    # Build the app
make test-php-unit            # Run PHP unit tests
make test-php-integration     # Run PHP integration tests
make test-php-style           # Check PHP code style
make dist                     # Create distribution package

Important Constraints

• Licensed under AGPL-3.0 (copyleft). Apache 2.0 migration planned.
• All contributions require a DCO sign-off.

OSPO Policy Constraints

GitHub Actions

• Only use actions owned by owncloud, created by GitHub (actions/*), verified on the GitHub Marketplace, or verified by the ownCloud Maintainers.
• Pin all actions to their full commit SHA (not tags): uses: actions/checkout@<SHA> # vX.Y.Z
• Never introduce actions from unverified third parties.

Dependency Management

• Dependabot is configured for automated dependency updates.
• Review and merge Dependabot PRs as part of regular maintenance.
• Do not introduce new dependencies without discussion in an issue first.

Translations

• When you add or change a translatable source string ($l->t() / p($l->t()) in templates/, or t() / n() in js/), you must add the matching entries to every l10n/<lang>.js and l10n/<lang>.json file.
• Keep each language's .js and .json pair in sync, and preserve each file's existing pluralForm; plural strings need one array element per nplurals.
• Translations are maintained in-repo (no Transifex); include them in the same PR as the source-string change.

Git Workflow

• Rebase policy: Always rebase; never create merge commits. Use git pull --rebase and git rebase before pushing.
• Signed commits: All commits must be PGP/GPG signed (git commit -S -s).
• DCO sign-off: Every commit needs a Signed-off-by line (git commit -s).
• Conventional Commits & Squash Merge: Use the Conventional Commits format where the repository enforces it. Many repos use squash merge, where the PR title becomes the commit message on the default branch — apply Conventional Commits format to PR titles as well. A reusable GitHub Actions workflow enforces this.

Context for AI Agents

Standard OC10 app with controller/service/db architecture. The REST API is documented in the wiki. Notes are stored as plain text files in user cloud storage.