Link docs pages by file path from the docs root

.agents/skills/translate/SKILL.md

@@ -112,14 +112,11 @@ what to do with it.
   translated button name points the reader at a button that does not exist.
 - Keep the same structure: same headings at the same levels, same lists,
   same callouts, same components.
-- Keep internal links as they are in the English. Do not add `/es/` or
-  `/fr/`; Docusaurus adds the locale when it builds the page.
-- The one exception: a relative link like `../deploy/portability.md` breaks
-  if the page it points to has no translation yet. Write it as the page's
-  full address instead, like `/documentation/deploy/portability`. If the
-  target page sets a `slug` in its front matter, the address is
-  `/documentation` plus the slug: `slug: /api-tokens` gives
-  `/documentation/api-tokens`, not the folder path.
+- Keep links exactly as they are in the English. Do not add `/es/` or
+  `/fr/`; Docusaurus adds the locale when it builds the page. If the English
+  has a relative link like `../deploy/portability.md`, it breaks the
+  translated build, so fix it in the English first (see the house style in
+  `AGENTS.md`).
 - Give translated headings the original English anchor so existing links
   still work.
 

AGENTS.md

@@ -82,9 +82,11 @@ Translations go in their own PR per locale and do not count toward the 20.
 ## House style
 
 - Every page has a `title` in its front matter.
-- Internal links start with `/documentation/`, `/adaptors/`, or `/articles/`.
-  Never use relative `.md` links; they break the build once a page is
-  translated.
+- Link to another docs page by its file path from the top of `docs/`, like
+  `/deploy/portability.md`. Link to adaptor pages and articles by URL, starting
+  with `/adaptors/` or `/articles/`. Never use relative links like
+  `../deploy/portability.md`; they break the build once only one of the two
+  pages is translated.
 - Images live in `static/img/` and are linked as `/img/filename`, with alt text
   that says what the image shows. "Screenshot" does not count.
 - Leave a blank line after an admonition's opening line (`:::tip`, `:::note`,

docs/build-for-developers/security-for-devs.md

@@ -178,6 +178,6 @@ adjusted by the OpenFn super admin.
 
 For more security considerations and best practices for all OpenFn implementers
 (not just developers), be sure to check out the complete
-[OpenFn Security Guidebook](../get-started/security.md). For more on job-writing, 
-see the [job-writing guide](../jobs/job-writing-guide.md).
+[OpenFn Security Guidebook](/get-started/security.md). For more on job-writing, 
+see the [job-writing guide](/jobs/job-writing-guide.md).
 :::

docs/build/channels.md

@@ -27,7 +27,7 @@ OpenFn.
 
 Channels are currently an experimental feature. To use them, enable
 **Experimental Features** on your
-[user profile](../manage-users/user-profile.md) page. If you don't see a
+[user profile](/manage-users/user-profile.md) page. If you don't see a
 `Channels` item in your project sidebar, this flag is the reason.
 
 :::
@@ -62,7 +62,7 @@ You need:
 
 - The **Experimental Features** flag enabled on your user profile
 - A **project** where you have the `Owner`, `Admin`, or `Editor`
-  [role](../manage-projects/user-roles-permissions.md) (Viewers can see channels
+  [role](/manage-projects/user-roles-permissions.md) (Viewers can see channels
   and their logs, but cannot create or change them)
 - The **URL of the destination service** you want to proxy to (a public API like
   `https://hacker-news.firebaseio.com/v0` works great for testing)
@@ -72,12 +72,12 @@ You need:
 Channels use two kinds of credentials, and both are optional:
 
 - **Client credentials** control who can send requests _to your channel_. They
-  are the same [webhook auth methods](../manage-projects/webhook-auth.md) used
+  are the same [webhook auth methods](/manage-projects/webhook-auth.md) used
   to secure webhook triggers (Basic HTTP Authentication or API Key
   Authentication) and are managed under `Webhook Security` in your project
   settings.
 - A **destination credential** is how OpenFn authenticates _to the destination
-  service_. It is a regular [project credential](./credentials.md), and OpenFn
+  service_. It is a regular [project credential](/build/credentials.md), and OpenFn
   uses it to build the `Authorization` header on every forwarded request.
   Channels currently support these credential types:
 
@@ -199,7 +199,7 @@ its **Requests** count or **Last Activity** on the Channels page.
 :::info
 
 Whether request and response payloads are stored follows your project's
-[Data Storage](../manage-projects/io-data-storage.md) settings. If your project
+[Data Storage](/manage-projects/io-data-storage.md) settings. If your project
 doesn't store I/O data, channel request metadata is still logged, but the
 payloads are wiped.
 

docs/build/steps/steps.md

@@ -141,5 +141,5 @@ want this and to avoid the risk of accidental upgrades on live Workflows.
 
 Click the code button `</>` displayed on the configuration panel to write or
 edit a Job expression to define the "rules" or the specific tasks to be
-completed by your Step. See the pages on [the Inspector](./step-editor.md) and
+completed by your Step. See the pages on [the Inspector](/build/steps/step-editor.md) and
 [writing Jobs](/documentation/jobs/job-writing-guide) to learn more.

docs/build/triggers.md

@@ -20,10 +20,10 @@ another OpenFn workflow, or manually (i.e., via cURL request).
 
 To learn about how to add an additional layer of security to your Webhook
 Trigger by adding authentication, head over to our
-[Webhook Security](../manage-projects/webhook-auth.md) page.
+[Webhook Security](/manage-projects/webhook-auth.md) page.
 
 Learn how a workflow's initial `state` gets built from a webhook trigger
-[here](../jobs/state#webhook-triggered-runs).
+[here](/jobs/state.md#webhook-triggered-runs).
 
 ## **Webhook Trigger Responses**
 

docs/build/troubleshooting.md

@@ -8,7 +8,7 @@ and complications, that might help you get to the bottom of it.
 
 :::tip
 
-Check out the [Troubleshooting page](../monitor-history/troubleshooting.md) in
+Check out the [Troubleshooting page](/monitor-history/troubleshooting.md) in
 the "Monitor History" section for more specific tips and common errors.
 
 :::

docs/build/workflow-snapshots.md

@@ -26,7 +26,7 @@ Click on the inspect icon in front of the step you would like to view.
 
 ![Inspect](/img/inspect.webp)
 
-This will open the [inspector screen](../build/steps/step-editor.md) for that step in the run with all associated artifacts: logs and input/output data. On the inspector, you'll notice that you're in a read-only mode, and hovering on the workflow snapshot ID chip, you’ll see a message that reads “You are viewing a snapshot of this workflow that was taken on ….”
+This will open the [inspector screen](/build/steps/step-editor.md) for that step in the run with all associated artifacts: logs and input/output data. On the inspector, you'll notice that you're in a read-only mode, and hovering on the workflow snapshot ID chip, you’ll see a message that reads “You are viewing a snapshot of this workflow that was taken on ….”
 
 ![Snapshot2](/img/snapshots2.webp)
 
@@ -60,4 +60,4 @@ When retrying a run with a snapshot, the retry will be executed with the latest
 
 As they save a workflow as a particular set of configuration, input data and job code, snapshots are mainly tools to help administrators with auditing and dealing with errors (such as, for example, why a case hasn't been updated correctly in a database). 
 
-OpenFn offers dedicated tools for [version control](../manage-projects/link-to-gh.md) that allows you and your team to manage changes in job code for faster and safer development, debugging and revision.
+OpenFn offers dedicated tools for [version control](/manage-projects/link-to-gh.md) that allows you and your team to manage changes in job code for faster and safer development, debugging and revision.

docs/build/workflows.md

@@ -15,9 +15,9 @@ To create a new Workflow in your Project:
 2. Click the **Create new workflow** button.
 3. Give your Workflow a descriptive `Name` (e.g., `Register patients`,
    `Refer cases`, `Monthly payroll`).
-4. Choose your [Trigger](../build/triggers.md)
-5. Edit your first [Step](../build/steps/steps.md)
-6. Modify the [Path Condition](../build/paths.md), if needed, to define _when_
+4. Choose your [Trigger](/build/triggers.md)
+5. Edit your first [Step](/build/steps/steps.md)
+6. Modify the [Path Condition](/build/paths.md), if needed, to define _when_
    the Workflow should proceed to the next Step.
 7. Configure more Steps as needed
 

docs/build/working-with-branches.md

@@ -3,7 +3,7 @@ title: Manage changes with GitHub branches
 sidebar_label: Manage changes
 ---
 
-In the [Edit Steps Locally](../build/editing-locally.md) section, we walked through
+In the [Edit Steps Locally](/build/editing-locally.md) section, we walked through
 the process of creating and adding your changes to the `main` branch of a
 project.
 
@@ -30,7 +30,7 @@ repo to your local folder.
    branch, managed separately from `main`.
 
 2. To test the changes locally, check out the
-   [The CLI](../build-for-developers/cli-intro.md) docs.
+   [The CLI](/build-for-developers/cli-intro.md) docs.
 
 3. Just as you've seen when working on `main`, when you're done check which
    files you changed with `git status`.

docs/contribute/roadmap.md

@@ -183,4 +183,4 @@ We encourage users to post their questions on the OpenFn Community at
 [community.openfn.org](https://community.openfn.org), or consider creating
 issues for bugs via product repository. You can also independently start
 contributing to the OpenFn software, adaptors, or documentation by getting
-started [here](./writing-code.md).
+started [here](/contribute/writing-code.md).

docs/deploy/options.md

@@ -74,7 +74,7 @@ local/government-managed servers, you might:
 8. **Monitor & adjust your strategy** as and when required by your country’s
    usage and data sovereignty requirements evolve over time.
 
-\*Head over to the [Requirements](./requirements.md) page for more information
+\*Head over to the [Requirements](/deploy/requirements.md) page for more information
 on recommended server specifications.
 
 ## Moving from cloud to local (v1 or v2)

docs/deploy/portability-v3.md

@@ -282,7 +282,7 @@ OpenFn [CLI](https://github.com/OpenFn/kit/tree/main/packages/cli) comes with
 commands that can be used to pull project configurations down from a running
 Lightning server, and to deploy or push updates to existing projects on a
 Lightning server. To learn more about automated version control via pull and
-deploy, head over to our [Version Control](../manage-projects/link-to-gh.md)
+deploy, head over to our [Version Control](/manage-projects/link-to-gh.md)
 docs.
 
 :::info Don't have the CLI yet?

docs/get-started/security-compliance.md

@@ -17,7 +17,7 @@ NGOs worldwide.
 ✓ Build “zero-persistence” data pipelines to fully control where data is stored
 
 ✓ Security implementation training & guidance for your project teams
-([read more](../get-started/security.md))
+([read more](/get-started/security.md))
 
 See our main website to learn more about OpenFn
 [Security & Trust](https://www.openfn.org/trust) and
@@ -41,11 +41,11 @@ In your digital ecosystem, typically **OpenFn serves as a data processing and
 transfer solution—not as a data storage service.**
 
 As an open source Digital Public Good, OpenFn can be deployed anywhere
-([see docs](../deploy/options.md)) and workflows can be configured to adhere to
+([see docs](/deploy/options.md)) and workflows can be configured to adhere to
 your organization's specific data sharing agreements and security policies.
 
 Consult the `Manage Projects` docs pages for more on project and
-[data storage settings](../manage-projects/io-data-storage.md).
+[data storage settings](/manage-projects/io-data-storage.md).
 
 See the below diagram for an example architecture where even the OpenFn Cloud
 can be configured as a **“zero-persistence” data pipeline** to ensure compliance
@@ -56,8 +56,8 @@ before migrating to a local deployment when they’re ready to scale.
 ![Sample Architecture](/img/zero-persistence.webp)
 
 To delete your project data at any time, you can
-[delete your project](../manage-projects/platform-mgmt.md) or
-[delete your account](../manage-users/user-profile.md).
+[delete your project](/manage-projects/platform-mgmt.md) or
+[delete your account](/manage-users/user-profile.md).
 
 ## Encryption
 
@@ -75,7 +75,7 @@ Learn more at [openfn.org/trust](https://www.openfn.org/trust#encryption).
 
 ## Credentials
 
-[Credentials](../manage-projects/manage-credentials.md), used to grant OpenFn
+[Credentials](/manage-projects/manage-credentials.md), used to grant OpenFn
 API access to your various technologies, are encrypted at rest so that, in the
 unlikely event of a database breach, without access to multiple, independently
 secured boxes an attacker would be unable to read your authentication
@@ -91,7 +91,7 @@ at [github.com/OpenFn/adaptors](https://github.com/OpenFn/adaptors).
 Credentials can only be viewed by you (the creator), and are loaded into your
 private runtime for job execution. You can delete these credentials at any time
 and they will be purged from the system.
-[See docs](../manage-users/user-credentials.md) for more on OpenFn credentials
+[See docs](/manage-users/user-credentials.md) for more on OpenFn credentials
 management and sharing.
 
 ## User Access Management and RBAC
@@ -105,19 +105,19 @@ scoped API tokens to ensure security and compliance.
 
 When new users are invited to work on your Project as Collaborators, they are
 assigned a role that determines their permissions. See docs on
-[Collaboration](../manage-projects/collaboration.md) and
-[User Roles](../manage-projects/user-roles-permissions.md) for more information.
+[Collaboration](/manage-projects/collaboration.md) and
+[User Roles](/manage-projects/user-roles-permissions.md) for more information.
 
 When users register for the platform, they will be prompted to create a secure
 password. OpenFn super administrators can also enable
-[Multi-Factor Authentication](../manage-users/user-profile.md), password expiry,
+[Multi-Factor Authentication](/manage-users/user-profile.md), password expiry,
 and stale account lockout.
 
 :::info More OpenFn Security Questions?
 
 First, be sure to consult the [Trust](https://www.openfn.org/trust) and
 [Compliance](https://www.openfn.org/compliance) pages on our website, as well as
-[Security Implementation Guidebook](../get-started/security.md).
+[Security Implementation Guidebook](/get-started/security.md).
 
 Ask questions on [Community](https://community.openfn.org/) or
 [contact our core team](mailto:security@openfn.org) for private queries.

docs/get-started/try-out.md

@@ -50,7 +50,7 @@ without limits. See our GitHub repo for developer docs:
 :::info Questions?
 
 Check out these docs for more details on specific features (see menu sidebar),
-browse the [main docs page](./home.md), or post your questions on
+browse the [main docs page](/get-started/home.md), or post your questions on
 [Community](https://community.openfn.org).
 
 :::

docs/jobs/javascript.md

@@ -288,7 +288,7 @@ For scenarios where you have a global list of variables or mapping rules that
 you would like to reference throughout your workflows, you can add these to your
 job as a constant that can be referenced repeatedly throughout the job
 expression. See the documentation on
-[mapping specifications](../design/mapping-specs.md) for more information on
+[mapping specifications](/design/mapping-specs.md) for more information on
 globals.
 
 ```js

docs/jobs/operations.md

@@ -127,7 +127,7 @@ post('/some-other-data', state => state.data);
 When `post` executes, it resolves any function arguments by calling them with
 the current state. This lazy evaluation pattern is fundamental to writing
 correct OpenFn jobs. See also the
-[Lazy State operator](./lazy-state-operator.md) for a shorthand syntax.
+[Lazy State operator](/jobs/lazy-state-operator.md) for a shorthand syntax.
 
 ## Callbacks and fn()
 

docs/jobs/state.md

@@ -51,7 +51,7 @@ the input state for a Run must be generated differently:
 
 - When manually creating a work order, you must select or generate your input
   manually (e.g., by creating a custom `Input` on the app or `state.json` file
-  if working locally [in the CLI](../build-for-developers/cli-intro.md)).
+  if working locally [in the CLI](/build-for-developers/cli-intro.md)).
 - When a work order is automatically created via a webhook trigger or cron
   trigger, state will be created as described below.
 

docs/manage-projects/collaboration.md

@@ -26,7 +26,7 @@ below:
 | Viewer | A user with access to a project but only limited to viewing the project settings and artifacts.                                                                                |
 
 You can learn more about the permissions of each role
-[here](../manage-projects/user-roles-permissions.md)
+[here](/manage-projects/user-roles-permissions.md)
 
 ### Add project collaborator(s)
 
@@ -71,4 +71,4 @@ through the pop up window. The owner of a project cannot be removed.
 
 :::tip The project collaborators page is also where you can configure failure
 alerts and digests for your projects. Learn more about it
-[in this guide](../manage-projects/notifications.md). :::
+[in this guide](/manage-projects/notifications.md). :::

docs/manage-projects/io-data-storage.md

@@ -37,7 +37,7 @@ sovereignty.
 :::tip
 
 Check out the docs page on
-[Security & Compliance](../get-started/security-compliance.md) for more on data
+[Security & Compliance](/get-started/security-compliance.md) for more on data
 storage and solution architectures that rely on OpenFn "zero-persistence" data
 pipelines.
 

docs/manage-projects/manage-credentials.md

@@ -181,4 +181,4 @@ Example Raw JSON credential body or `configuration`:
 
 All credentials are stored encrypted at rest, and credential secrets can only be
 viewed by credential owners. See OpenFn
-[Security docs](../get-started/security-compliance.md) for more information.
+[Security docs](/get-started/security-compliance.md) for more information.

docs/manage-projects/oauth.md

@@ -33,8 +33,8 @@ For every application you need to connect to OpenFn, you need to set up at least
 one client for your project(s).
 
 Oauth clients can be set up either on the
-[project credentials page](../manage-projects/manage-credentials.md) or the
-[user credentials page](../manage-users/user-credentials.md).
+[project credentials page](/manage-projects/manage-credentials.md) or the
+[user credentials page](/manage-users/user-credentials.md).
 
 ### Creating an OAuth client
 
@@ -57,8 +57,8 @@ application. (Note: You should substitue `https://app.openfn.org/` with _your_
 OpenFn's deployment base URL if you're not using app.openfn.org.)
 
 For app-specific guidance (e.g., how to set up an Oauth Client
-[for Google Sheets](../adaptors/googlesheets)), refer to the relevant
-[Adaptor documentation](../adaptors) for app-specific guidance
+[for Google Sheets](/adaptors/googlesheets)), refer to the relevant
+[Adaptor documentation](/adaptors) for app-specific guidance
 
 :::
 
@@ -150,7 +150,7 @@ be permanently deleted after 7 days.
 ### More on Managing Credentials
 
 Go to the docs on
-[managing user credentials](../manage-users/user-credentials.md) to learn more
+[managing user credentials](/manage-users/user-credentials.md) to learn more
 about credential management for the applications you are integrating with on
 OpenFn.