Block edit and feedback links

Each labelled block’s links back to where it can be changed: [edit] opens the block’s Markdown source in GitHub’s editor on main, and [feedback] opens a new GitHub issue about the block, from the folio’s .github/ISSUE_TEMPLATE/block-feedback.yml when it has one (prefilling only the fields it declares: block, section, source, page, url) or as a plain issue whose body carries the same facts. The document build draws these on every block; this Tool prints them as JSON for one block or all. Governed by the block-actions skill.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

block-actions

Every block of a rendered document links back to where it can be changed: [edit] opens the block’s Markdown source in GitHub’s editor, and [feedback] opens a GitHub issue about that block, from the folio’s own issue form when it has one, listing the change-sets that already discuss the block. Use when a reader, reviewer or agent needs to propose a change to one block, when setting up a folio’s feedback issue form, or when a document site’s links point nowhere.

Source: folio-assistant-core/skills/content/folio-document-adapter/block-actions.md.

The skill declares no I/O contract (schemas/skills/block-actions/{input,output}.schema.json).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
inrepoRepoPathThe folio’s repository root. Default: the working directory.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inblockNodeIdOne block’s label. Absent: every block of every document. A label no block has exits 1.string · pattern ^[A-Za-z_][A-Za-z0-9_-]*$ · A node id within a BPMN process, e.g. A_Implement
ingithubRepoFullNameowner/name on GitHub. Default GITHUB_REPOSITORY, else the checkout’s origin. None at all exits 2: no links rather than broken ones.string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*\\/[A-Za-z0-9][A-Za-z0-9._-]*$ · A forge repository’s full name, owner/name
inedit-branchBranchThe branch [edit] opens. Default main.string · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]*$ · A git branch name
inissue-templateRepoPathThe issue form’s file name under .github/ISSUE_TEMPLATE/. Default block-feedback.yml, used only if the folio has it.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outlinksRepoPathJSON on stdout: one { label, source, section, edit, feedback } per block. A one-line summary goes to stderr.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.

Processes and tasks

No process step names a skill this Tool satisfies.

How it is deployed and reached

  • Command line. From the repository root: bun run folio-assistant-core/scripts/block-actions.ts.
  • GitHub Actions. No workflow in this checkout runs its command.

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun
networkno
when to choose it
whenA reader, reviewer or agent wants to propose a change to, or give feedback on, one block of a document folio, and needs the link that lands on that block rather than on the repository.
limitsBuilds URLs; it writes nothing to GitHub. Only labelled blocks get links. The issue form’s fields are read by a line scan for id:, so a form must declare its ids plainly.
costMilliseconds: one walk of the document manifests. No network.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/block-actions.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/block-actions.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.jsonld",
  "name": "block-actions",
  "title": "Block edit and feedback links",
  "description": "Each labelled block's links back to where it can be changed: [edit] opens the block's Markdown source in GitHub's editor on `main`, and [feedback] opens a new GitHub issue about the block, from the folio's `.github/ISSUE_TEMPLATE/block-feedback.yml` when it has one (prefilling only the fields it declares: block, section, source, page, url) or as a plain issue whose body carries the same facts. The document build draws these on every block; this Tool prints them as JSON for one block or all. Governed by the `block-actions` skill.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run folio-assistant-core/scripts/block-actions.ts"
  },
  "io": {
    "inputs": [
      {
        "name": "repo",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The folio's repository root. Default: the working directory.",
        "required": false,
        "arg": {
          "flag": "--repo"
        }
      },
      {
        "name": "block",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/NodeId",
        "description": "One block's label. Absent: every block of every document. A label no block has exits 1.",
        "required": false,
        "arg": {
          "flag": "--block"
        }
      },
      {
        "name": "github",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoFullName",
        "description": "`owner/name` on GitHub. Default `GITHUB_REPOSITORY`, else the checkout's `origin`. None at all exits 2: no links rather than broken ones.",
        "required": false,
        "arg": {
          "flag": "--github"
        }
      },
      {
        "name": "edit-branch",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Branch",
        "description": "The branch [edit] opens. Default `main`.",
        "required": false,
        "arg": {
          "flag": "--edit-branch"
        }
      },
      {
        "name": "issue-template",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The issue form's file name under `.github/ISSUE_TEMPLATE/`. Default `block-feedback.yml`, used only if the folio has it.",
        "required": false,
        "arg": {
          "flag": "--issue-template"
        }
      }
    ],
    "outputs": [
      {
        "name": "links",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "JSON on stdout: one `{ label, source, section, edit, feedback }` per block. A one-line summary goes to stderr."
      }
    ]
  },
  "satisfies": [
    "block-actions"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "A reader, reviewer or agent wants to propose a change to, or give feedback on, one block of a document folio, and needs the link that lands on that block rather than on the repository.",
    "limits": "Builds URLs; it writes nothing to GitHub. Only labelled blocks get links. The issue form's fields are read by a line scan for `id:`, so a form must declare its ids plainly.",
    "cost": "Milliseconds: one walk of the document manifests. No network."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev