---
name: mdshare
description: Publica Markdown em link permanente e fecha o ciclo de revisão com humanos. Gatilhos - "publica", "compartilha", "gera link", "manda pro fulano revisar", "o que comentaram", "aplica os comentários", "mdshare". Use quando terminar um documento que alguém precisa ler, revisar ou comentar.
license: Uso interno Fibersals
metadata:
  base_url: https://mdshare-a2m.pages.dev
  internal_url: https://mdshare.fibersals.com.br
  api_reference: https://mdshare-a2m.pages.dev/llms.txt
---

# MDShare

Publica um documento Markdown num link permanente, recebe comentários ancorados
a trechos exatos do texto e devolve esses comentários de volta para você agir.

**O ciclo:** você publica → o humano lê e comenta o trecho → você lê os
comentários, corrige e resolve. Tudo na mesma URL.

Referência completa da API: <https://mdshare-a2m.pages.dev/llms.txt>

---

## Quando usar

- O usuário pediu para publicar, compartilhar ou gerar link de um `.md`
- Você produziu um relatório, análise ou proposta que alguém precisa revisar
- O usuário perguntou o que comentaram num documento
- O usuário pediu para aplicar os comentários de um documento

## Quando não usar

- Texto curto que cabe na conversa: responda direto
- Conteúdo que não deve sair da máquina: a publicação envia o arquivo ao MDShare.
  Antes de compartilhar, confira se o documento deve ser privado, protegido por
  senha ou aberto por link.

---

## 0. Autenticar

Publicar e atualizar exige um **token de agente** (ou estar num IP da
whitelist). Peça o seu a quem administra o MDShare e guarde em
`MDSHARE_TOKEN`; ele começa com `mds_`.

```bash
export MDSHARE_TOKEN=mds_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Sem token e fora da whitelist, a API responde 403 explicando o que falta.
Token sem escopo suficiente responde 403 dizendo qual escopo falta; token
revogado responde 401.
Para apagar documento ou revisão, um agente precisa do escopo `delete` e de
permissão para gerenciar o documento. Um token só com `publish` não apaga.

## 1. Publicar

```bash
curl -s -X POST https://mdshare-a2m.pages.dev/api/upload \
  -H "Authorization: Bearer $MDSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg md "$(cat relatorio.md)" '{markdown: $md}')"
```

Resposta: `{"success":true,"id":"8f14e45f","url":"https://.../view/8f14e45f","revision":1}`

**Guarde o `id`.** A convenção é gravá-lo no frontmatter do arquivo fonte:

```yaml
---
mdshare_id: 8f14e45f
---
```

O frontmatter não aparece para quem lê: o visualizador o suprime. Ele continua
no armazenamento e nas respostas da API, então mantenha-o no arquivo.

Para revisor externo à Fibersals, publique com senha e entregue as duas coisas:

```bash
-d '{"markdown":"...","password":"vistoria2026"}'
```

Num documento privado, a conta Fibersals só abre o link se for proprietária ou
tiver recebido acesso. Se o documento tiver senha, quem não recebeu convite
pode usá-la; sem senha, precisa ser convidado. A entrada com Google fica em
`https://mdshare.fibersals.com.br/view/{id}`.

## 1b. Compartilhar com pessoas específicas

Publique com `owner` e a lista de convidados na mesma chamada. O documento
nasce privado e cada pessoa entra com a conta Google — sem senha.

```bash
curl -s -X POST https://mdshare-a2m.pages.dev/api/upload \
  -H "Authorization: Bearer $MDSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"markdown":"# Proposta\n\nTexto.",
       "owner":"ddutra@fibersals.com.br",
       "share":[{"subject":"marina@fibersals.com.br","role":"commenter"}]}'
```

Depois, para mudar quem tem acesso:

```bash
curl -s -X PUT https://mdshare-a2m.pages.dev/api/8f14e45f/share \
  -H "Authorization: Bearer $MDSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject":"marina@fibersals.com.br","role":"commenter"}'

curl -s -X PUT .../share -d '{"owner":"marina@fibersals.com.br"}'   # transferir
curl -s -X DELETE ".../share?subject=marina@fibersals.com.br"       # revogar
```

`role`: `viewer` (lê), `commenter` (comenta) ou `manager` (compartilha também).
Só o proprietário ou a administração pode transferir a propriedade.
Use `"subject":"@fibersals.com.br"` para liberar o domínio inteiro, e
`{"visibility":"link"}` para reabrir o documento a quem tiver o endereço.

## 2. Atualizar (mesmo link, revisão nova, comentários preservados)

```bash
curl -s -X PUT https://mdshare-a2m.pages.dev/api/update \
  -H "Authorization: Bearer $MDSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg id "8f14e45f" --arg md "$(cat relatorio.md)" '{id: $id, markdown: $md, baseRevision: 3}')"
```

**Regra de ouro:** se o arquivo tem `mdshare_id` no frontmatter, sempre atualize
em vez de publicar de novo. O link já foi entregue para alguém.

Antes de editar, leia `GET /api/{id}` e guarde a revisão e o `ETag`. Toda
atualização exige essa precondição; sem ela a API responde `428`. O exemplo
acima parte da revisão 3. Acrescente `"baseRevision":3` ao JSON ou envie `If-Match: "rev-3"` no
cabeçalho. Se houver outra revisão, a API responde `409`: leia a versão nova
e concilie as alterações antes de tentar de novo. Para repetir a mesma chamada após uma falha de rede,
use a mesma `Idempotency-Key`; isso evita uma revisão duplicada.

## 3. Ler os comentários

A forma direta — o documento com cada comentário delimitado no trecho exato:

```bash
curl -s "https://mdshare-a2m.pages.dev/api/8f14e45f?format=commented&status=open"
```

```markdown
O telhado apresenta **{{{c1}}}infiltração na face sul{{{/c1}}}**, com manchas.

{{{comments
c1 id=3f9a1c2b7d4e5061 status=open author="Eng. Marina" email=marina@fibersals.com.br revision=2
    Isso já foi tratado na vistoria de 2025?
}}}
```

Se preferir JSON: `GET /api/8f14e45f/comments?status=open`.

Uma anotação com `kind: "suggestion"` propõe trocar texto. A resposta inclui
`original`, `proposed`, `sourceStart`, `sourceEnd`, `baseRevision` e `hash` do
Markdown fonte. Compare o trecho original com a proposta e confira a revisão
antes de aplicar. O servidor recusa sugestões cujo hash ou trecho não bate com
o documento.

Comentários e sugestões podem incluir imagens coladas. Envie
`images: [{"name":"foto.png","data":"BASE64"}]` junto com a anotação e
referencie cada arquivo em `body` ou `proposed` com
`![Vistoria](mdshare-image:foto.png)`. A resposta troca a referência por
`/img/{id}/{arquivo}`. Ao aplicar a sugestão, mantenha essa URL no Markdown.
Ela segue as permissões do documento e permanece disponível até excluir o
documento, incluindo imagens de anotações excluídas. Aceita até cinco imagens
PNG, JPEG, GIF ou WebP, com 8 MiB por arquivo e 20 MiB no total; SVG não entra
nesse fluxo. Preserve o original, offsets e hash da sugestão.

Para mencionar uma pessoa, procure usuários registrados e com acesso em
`GET /api/{id}/mentions?q=nome`, usando sua identidade autorizada a comentar.
Escreva `@pessoa@fibersals.com.br` em `body`. Também funciona em respostas e
justificativas; menções em `proposed`, código e imagens não enviam avisos.
Mencionar não concede acesso. A senha anônima não permite consultar pessoas
nem gerar emails.

A resposta inclui `mentions` e `notificationStatus: {state,total,sent}`.
`pending` é fila; `sent` é aceite do provedor, sem garantia de chegada à caixa
de entrada. Sem envio configurado, a fila fica pendente e o comentário segue
salvo. Limites: dez destinatários por comentário e 50 avisos por dia por
identidade. Replay e edição não reenviam avisos já aceitos; remoção da menção,
exclusão ou revogação de acesso cancela pendências.

Para documento com senha, obtenha o token antes:

```bash
TOKEN=$(curl -s -X POST https://mdshare-a2m.pages.dev/api/auth \
  -H "Content-Type: application/json" \
  -d '{"id":"8f14e45f","password":"vistoria2026"}' | jq -r .token)
# e mande em todas as chamadas: -H "Authorization: Bearer $TOKEN"
```

## 4. Agir e fechar

1. Corrija o markdown conforme cada comentário.
2. **Remova os delimitadores `{{{cN}}}`** — são anotação, não conteúdo.
3. Publique com `PUT /api/update`.
4. Resolva cada comentário aplicado:

```bash
curl -s -X PATCH https://mdshare-a2m.pages.dev/api/8f14e45f/comments/3f9a1c2b7d4e5061 \
  -H "Content-Type: application/json" -d '{"status":"resolved"}'
```

Repita do passo 3 até não sobrar comentário aberto.

**Leia os comentários antes de publicar a correção.** Comentário pertence à
revisão em que foi feito: ao publicar a revisão nova, o painel dela começa
vazio. Os anteriores continuam acessíveis em
`GET /api/{id}/comments?revision=N` e ao trocar a revisão no visualizador —
mas quem estiver lendo a revisão nova não os verá.

Quem gerencia pode trocar a senha sem criar revisão com
`PUT /api/{id}/password` e JSON `{"password":"nova senha"}`, ou removê-la
com `DELETE /api/{id}/password`. O painel `/documents/` mostra propriedade,
visibilidade, pendências e senha; `GET /api/docs` devolve a mesma listagem com
filtros e páginas. O criador pode ser uma pessoa ou o token do agente que
publicou o documento.

---

## Regras que evitam erro

1. **Resolva o que aplicou.** Se a correção altera justamente o trecho
   comentado, a âncora deixa de achar o texto e o comentário vira órfão na
   revisão nova. Marque como `resolved` no mesmo momento em que corrigir.
2. **Olhe o campo `revision`.** O comentário pode ter sido escrito sobre uma
   versão anterior.
3. **Confira o que estiver marcado.** Na legenda:
   `scope=documento` é comentário geral, sem trecho;
   `scope=nao-localizado` significa que o trecho não existe mais;
   `scope=aproximado` significa que o trecho aparece repetido e a posição é um
   palpite — leia em volta antes de mexer.
4. **Não invente comentário resolvido.** Resolver é dizer ao humano que aquilo
   foi tratado. Se você não aplicou, deixe aberto e explique.
5. **Fotos ganham miniatura e lightbox.** Escreva
   `![Descrição](foto.webp)` e, no parágrafo seguinte, `**data** — Descrição.`:
   repetir a descrição é o que faz o parágrafo virar legenda da figura. Fotos em
   sequência viram grade de 2 colunas; título ou parágrafo de corpo entre elas
   quebra a sequência.
6. **Imagens locais** viram base64 no upload:
   `{"markdown":"...","images":[{"name":"foto.jpg","data":"<base64>"}]}` e
   referencie como `![alt](foto.jpg)` no markdown.
   Upload e atualização aceitam PNG, JPG/JPEG, GIF, WebP e SVG. Envie até 20
   imagens por chamada, com até 8 MiB cada e 25 MiB no total após decodificar
   Base64. Os nomes não podem conter pastas, barras, `..` ou caracteres de
   controle, nem se repetir após normalização para nomes seguros. MIME específico
   deve corresponder à extensão. A API retorna 400 para dados inválidos e 413
   para tamanho excedido, antes de publicar conteúdo.

O campo legado `isPublic` em uma publicação com senha não significa que o
documento seja público. Confira `visibility` e `hasPassword` no catálogo ou
em `GET /api/{id}/share`, conforme sua permissão.

## Responder ao usuário

Depois de publicar, entregue o link e diga o que fazer com ele:

> Publiquei em https://mdshare-a2m.pages.dev/view/8f14e45f
> Selecione qualquer trecho para comentar — eu leio os comentários e corrijo.

Depois de aplicar comentários, diga o que foi feito e o que ficou de fora:

> Apliquei 3 dos 4 comentários e publiquei a revisão 4. Deixei aberto o da
> Marina sobre a área comprometida: preciso do número da medição para corrigir.