client.guidelines

Bases: SyncResource

Sync project-guidelines namespace (client.guidelines).

get

get(project_id: UUID | str) -> ProjectGuideline

Read the guideline (any project member). Image URLs are refreshed to fresh 1-hour presigned GETs before return.

Raises:

Type	Description
ForbiddenError	caller is not a project member (AUTH_FORBIDDEN).
NotFoundError	PROJECT_NOT_FOUND.

upsert

upsert(project_id: UUID | str, *, content_md: str) -> ProjectGuideline

Create or replace the guideline Markdown (manager-only). Returns the refreshed guideline (same shape as :meth:get).

Parameters:

Name	Type	Description	Default
content_md	str	Markdown source (CommonMark + GFM), 1 MB cap.	required

Raises:

Type	Description
UnprocessableError	content_md over the 1 MB cap (VALIDATION_ERROR).
PayloadTooLargeError	over the byte cap (PAYLOAD_TOO_LARGE).
ForbiddenError	caller is not a project manager (AUTH_FORBIDDEN).

init_image_upload

init_image_upload(project_id: UUID | str, *, filename: str, size_bytes: int, content_type: str) -> GuidelineImageUpload

Mint a presigned PUT for a guideline image (manager-only, 201).

Parameters:

Name	Type	Description	Default
content_type	str	image MIME type; must be an accepted image format.	required
size_bytes	int	exact byte count; 10 MB per-image cap.	required

Raises:

Type	Description
BadRequestError	unsupported image MIME (ASSET_FORMAT_UNSUPPORTED).
UnprocessableError	size_bytes over the 10 MB cap (VALIDATION_ERROR).
PayloadTooLargeError	over the byte cap (ASSET_TOO_LARGE).
ForbiddenError	caller is not a project manager (AUTH_FORBIDDEN).

Response models

Models returned by client.guidelines methods (fields, types, and what each means).

Project-guideline models (the guidelines resource, ADR-0045).

The guideline is a single Markdown document per project plus a presigned image-upload flow. On read, the server re-signs any image URL pointing at the project's guidelines/{project_id}/... prefix to a fresh 1-hour presigned GET.

ProjectGuideline

Bases: BaseModel

The project's Markdown guideline. content_md is empty (never absent) when no guideline has been written yet — the server default-fills it.

GuidelineImageUpload

Bases: BaseModel

Presigned URLs for a guideline image upload. PUT the bytes to upload_url, then embed public_url in the guideline Markdown.