Claude Notes

This repository represents our collective and ongoing learnings from applying Claude at Teak.

At present, we're using Opus 4.5 exclusively. There may be "cruft" in our learnings as new models come out so keep an eye on how recently a given document (or given section of a document) was updated and adjust your expectations accordingly.

Workstation Setup

First setup Homebrew, and make sure everything is up to date.

Clone this repo and cd into it. Run the following to set up tools:

brew bundle
nvm use
# N.B. You may need to run `nvm install; corepack enable; rehash` here!
yarn

Development

# Regenerate all PDFs, then watch for changes to Markdown files and re-generate as-needed.  Press ctrl-c to terminate:
yarn watch
# Files will be generated alongside the Markdown sources.

# As above, but only for one specific file:
yarn watch-file <path-to-markdown-file>

# Build PDFs as a one-off operation:
yarn build

# Check Markdown files for lint:
yarn lint

# Look at counts of offenses by file:
yarn lint:offenders

# Lint specific file(s):
yarn lint:file <filename(s)>

# Automatically fix auto-fixable Markdown lint issues:
yarn lint --fix

# Fix a few other issues:
yarn normalize

Markdown Syntax

See this guide for the details of Github Flavored Markdown, in which all documents are authored.

In some cases, there is inline HTML used for things that Markdown cannot handle.

Iterating

When iterating on files using yarn watch, you will want a PDF viewer that can watch for changes and reload.

Skim is one such option. Use brew install skim to obtain it. You will need to enable the Sync option, in preferences.

NOTE: When changing the stylesheet, you will need to hit save on a .md file for it to be updated. The watch functionality does not track changes in dependencies!

Changing the Header/Footer

The first thing to note is that the logo is embedded as a data: URL. If updating the file in assets/, you will then need to run this command, and update config.js with the result:

base64 -i assets/teak-logo-color.png

The next thing is to note that HTML/CSS in the header/footer does not seem to behave as normal. Some limitations:

1. Layout happens independent of page content, and can easily be covered by it.
   • Adjust page margins accordingly!
2. Some attributes, like background-color don't seem to work. If you're trying to determine if you have overlap, use border: 1px solid #000.
3. Styles in included stylesheets do not seem to be available.

NOTE: When changing the header/footer, you will need to restart yarn watch to see the results. The watch functionality does not track changes in its own config!

Appendices, and Page Breaks

By default, page breaks happen "naturally", and so content of sections can/will be split across pages. In some cases, we want to ensure page breaks happen before a section -- notably, before the start of each appendix. To force a page break, add this, with a blank line before and after, where you want the page break to occur:

<div class="pagebreak"></div>